目的
- Pythonの各バージョンごとのテストを自動化する。
- カバレッジを計測できるようにする。
- テスト結果、カバレッジ計測結果をリポジトリのREADME.mdでバッジ表示し可視化する。
背景
OSS開発に向けた勉強の一環でPythonのライブラリを開発したが、サポートバージョンのテストを全て手動で回すのは現実的ではないため、CI等を導入しテスト、カバレッジ計測の自動化を検討していた。
調べた際、テスト実行等のworkflowを定義できるGitHub Actions、テスト時に計測したカバレッジを受け取り可視化するCodecovというサービスを見つけた。
GitHub Actionsとは
GitHubが提供するCI/CDサービスです。
様々なworkflowをGitHub内のイベントに応じて実行できます。
実行されるworkflowは様々なものが用意されており、自身で1から作ることもできますが、既存のworkflowを利用、改良することも可能です。
リポジトリの公開設定によって利用制限があります。
publicリポジトリやセルフホストランナーの場合は無料のようです。privateリポジトリについては一定の制限があります。
支払いにも関わり、本投稿では鮮度を保てないため下記公式ページを参照とします。
Codecovとは
CIで実行したテストカバレッジの計測結果を受け取り、それを可視化するサービスです。
このサービス自体がテストの実行やカバレッジの計測をするわけではなく、結果を受け取りそれを可視化するというやりとりが行われます。
こちらもオープンソースについては無料のようです。
全体像
こんなことをします。
テストの自動化
workflowが用意されているためそれを改良し利用します。
テストを実行するworkflowを追加
GitHubリポジトリのActionsタブで、New workflowボタンを押します。
python testで検索し、検索結果から赤枠のworkflowのConfigureボタンを押します。見つからない場合は条件を追加し絞り込んでください。
他にも似たようなworkflowがありますが、説明文をよく確認しましょう。今回はサポートするバージョン全てに対してテストを行いたいため、複数のPythonバージョンでパッケージの試験と説明があるworkflowを選択します。
追加したworkflowを編集
workflow名称、テスト対象Pythonバージョンに変更がない場合は本項の内容は不要です。
その場合、後続の説明にてunit-testというworkflow名称が出てきますが、読み替えて手順を操作してください。
下記のような画面が表示されるため、任意のファイル名（今回はunit-testにしました）に変更しコードを編集します。
コードの編集箇所は下記です。冒頭のnameについても任意ですが、今回はunit-testにしました。
テスト対象のPythonバージョンはお好きに編集してください。私は3.7でもテストしたかったため追加してあります。
本投稿では変更しませんが、冒頭のon:の箇所がworkflowの実行タイミングです。
このworkflowの実行タイミングはmasterブランチへのpush、pull_requestマージが指定されています。
ブランチについてはお使いのリポジトリに合わせ編集願います。
# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
- name: Python package
+ name: unit-test
on:
push:
branches: [ "master" ]
pull_request:
branches: [ "master" ]
jobs:
build:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
- python-version: ["3.8", "3.9", "3.10"]
+ python-version: ["3.7", "3.8", "3.9", "3.10"]
（省略）
編集が完了したら右上のStart commitボタンを押しコミットします。
コミットメッセージ等求められますが、任意で入力願います。
workflowの実行結果を確認
Actionsタブを表示し、作成したworkflowを選択すると、結果が表示されます。実行中の場合はしばらく待つと反映されます。
workflowの実行結果をバッジで表示
（2022/8/28追記 workflowの実行結果画面からバッジ作成方法を追記）
workflowの実行結果画面にバッジ作成メニューがあります。
公式にもバッジの追加方法があります。
README.md等に下記を追加することでバッジ表示できます。
[](https://github.com/{ユーザ}/{リポジトリ}/actions/workflows/unit-test.yml)
こんな感じで表示されます。
カバレッジの計測、連携
事前にCodecovへのユーザ登録を行なった上で以降の操作を行います。
未登録の方は登録をお願いします。
CodecovとGitHub Actionsとの連携については下記にチュートリアルがあります。
本手順はチュートリアルに沿って、必要な操作のみを行います。
Codecov GitHubアプリのインストール
Codecovチュートリアルページのリンク先からインストールします。
赤枠のリンクをクリックします。
インストールページが表示されるためインストールします。
Codecov GitHubアプリのインストール確認
GitHubの右上ユーザアイコンからメニューを開き、Settings＞Applications＞Installed GitHub Appsと辿ります。
一覧にCodecovが表示されていればインストール成功です。
workflowにカバレッジ計測、計測結果アップロード処理を追加
コードの編集箇所は下記です。
カバレッジ計測ライブラリのpytest-covのインストール、pytestへカバレッジ計測、レポート出力の指定を追加、計測結果のアップロード処理を追加します。
# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
name: unit-test
（省略）
- name: Install dependencies
run: |
python -m pip install --upgrade pip
- python -m pip install flake8 pytest
+ python -m pip install flake8 pytest pytest-cov
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
- name: Lint with flake8
run: |
# stop the build if there are Python syntax errors or undefined names
flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
# exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
- name: Test with pytest
run: |
- pytest
+ pytest --cov=./テスト対象のディレクトリ --cov-report=xml
+ - name: Upload coverage reports to Codecov with GitHub Action
+ uses: codecov/codecov-action@v3
pytest実行時のオプション--covに指定するパスを限定的にしなかった場合（./等の上位のディレクトリを指定した場合）、ディレクトリ構造にもよりますが、pypiへの登録スクリプトsetup.py等の意図していないソースも対象となってしまい、カバレッジ100%とならない場合があります。
その際はテスト対象のソースが置かれたディレクトリを指定する等、限定的な指定とするか、pytest-covの設定で除外設定を指定する等対応をしてください。
workflowの実行結果を確認
下記ページにアクセスし結果を確認します。
カバレッジ計測結果が右側赤枠に表示されます。リポジトリ名のリンクを辿れば、計測結果の詳細を確認できます。
Codecovに連携したカバレッジ測定結果をバッジで表示
前項の一覧画面でリポジトリ名をクリックします。
Settingsタブを選択します。
Badges & Graphsメニューを選択するとバッジ表示のコードが表示されます。お好きな形式をコピーし利用してください。
こんな感じで表示されます。
参考
参考となるリポジトリを掲載します。勉強のために作成したもののため、OSS自体の質は気にしないでください。
レイアウト崩れが発生してしまったため、バッジの表示コードは本投稿とは少し違いますがご了承願います。
最後に
実務でCIが導入されているプロジェクトに配置されたことはあったが、自身で構築やカスタマイズをした経験はなかった。
本投稿で構築した内容は簡単なものではあるが、どのCIにおいても目的や本質部分は同じのため、入門知識としてはいいものが得られたと思う。
pipyへのデプロイについてもGitHub Actionsで自動化ができるらしいので、今後他のworkflowも構築し自動化や効率化をしたい。