Pythonでのドキュメント化
nabetsuDocstrings
- Google StyleやNumpy Styleなど書き方がいくつかある
ドキュメントの出力
mkdocs-materialとmkdocstringsを組み合わせることでdocstringをHTMLページで確認できる。
手順1 設定ファイルの作成
プロジェクトのルートディレクトリに設定ファイルを作成する。
site_name: sample docs
theme:
name: "material"
plugins:
- search
- mkdocstrings
手順2 referenceファイルの作成
docsフォルダの中にリファレンスファイルを作成し、ドキュメント作成対象を指定する。
docsフォルダ内のディレクトリ構造が最終的に作成されるドキュメントの構造に反映される。
# sample module
::: src.functions.sample
手順3 ローカルでの確認
mkdocs serveでHTMLファイルをサーブしてみると以下の通り表示される。
参考資料
nabetsuテストレポート
HTML形式
pytest-htmlをインストールした上で以下のコマンドを実行することでHTML形式のレポートを出力できる。
pytest --cov=functions/ tests/unit --html=index.html
出力内容のカスタマイズ
pytestからテスト仕様書ぽいものを生成する - tamaosa.com にあるように、conftest.py等でレポートへの新たな項目の追加などが設定できる。
XML形式
実行時のオプションに--junitxml=foo.xmlとつけることでJunit形式のxmlを出力できる。[[GitLab]]等のCIサービスで利用する際に便利。
pytest --cov=functions/ tests/unit --junitxml=report.xml
カバレッジレポート
カバレッジの計測
pytest-covというライブラリをインストールすることで、テストのカバレッジを出力することができる。
インストール自体は通常のライブラリと同様pipから行えばOK
pip install pytest-cov
後はpytestの実行時にカバレッジの取得対象となるソースコード、テストコードの順で指定を行えばカバレッジが取得される
pytest -v --cov=src tests
カバレッジは以下のような内容でコンソールに表示される。
$ python -m pytest tests --cov=src
...
tests/unit/test_add.py . [ 33%]
tests/unit/test_multiply.py . [ 66%]
tests/unit/test_substruct.py . [100%]
----------- coverage: platform linux, python 3.9.5-final-0 -----------
Name Stmts Miss Cover
--------------------------------------
src/add.py 2 0 100%
src/multiply.py 2 0 100%
src/substruct.py 2 0 100%
--------------------------------------
TOTAL 6 0 100%
HTML形式での出力
cov-reportを引数として設定することでHTML形式のレポートが出力できる。（出力先としてhtmlcovというディレクトリが生成される）
python -m pytest tests --cov=src --cov-report=html
注意点として、cov-reportで形式を指定するとコンソールへの出力は行われなる。GitLab等のCIサービスでコンソールへの出力結果からカバレッジ率を取得したい場合には、上記の設定だけだと取得出来なくなってしまう。
複数の形式で同時に出力
解決策としては、pytest-cov - Reportingに記載の通りcov-reportは複数指定可能なので、コンソールへの出力を意味する--cov-report termを追加すればOK
以下のイメージでコンソールでの出力とHTMLへの出力が同時に行われる
$ python -m pytest tests --cov=src --cov-report=html --cov-report=term
...
tests/unit/test_add.py . [ 33%]
tests/unit/test_multiply.py . [ 66%]
tests/unit/test_substruct.py . [100%]
----------- coverage: platform linux, python 3.9.5-final-0 -----------
Name Stmts Miss Cover
--------------------------------------
src/add.py 2 0 100%
src/multiply.py 2 0 100%
src/substruct.py 2 0 100%
--------------------------------------
TOTAL 6 0 100%
Coverage HTML written to dir htmlcov