GitHub ActionsとCodecovでテスト・カバレッジ計測を自動化、README.mdに結果をバッジ表示する。

目的

• 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マージが指定されています。
ブランチについてはお使いのリポジトリに合わせ編集願います。

python-package.yml

# 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等に下記を追加することでバッジ表示できます。

例

[![unit-test](https://github.com/{ユーザ}/{リポジトリ}/actions/workflows/unit-test.yml/badge.svg)](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へカバレッジ計測、レポート出力の指定を追加、計測結果のアップロード処理を追加します。

unit-test.yml

# 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も構築し自動化や効率化をしたい。