コードの記述、実行、およびテスト

バグの修正や機能の実装には、新しいコードを書く必要があります。

コードの開発を始めるには、開発環境が設定されていることと、ブランチ上で作業していることを確認してください。

BeeWareのコード作成に関するガイドラインをまとめたコードスタイルガイドを用意しています。

テスト駆動開発

コードが期待どおりに動作することを確実にする良い方法は、まずそれを検証するためのテストケースを作成することです。テスト対象のコードはまだ存在しないため、このテストケースは当初は失敗するはずです。その後、テストに合格するために必要なコードの変更を加えれば、自分が書いたコードが期待通りの問題を解決していることが確認できます。

コードを実行する

コードを記述したら、それが正常に動作することを確認する必要があります。期待どおりに動作しているかを確認するために、手動でコードを実行する必要があります。まだ行っていない場合は、変更内容に対するテストケースを作成することをお勧めします。前述の通り、コードがコメントアウトされているか、存在しない場合、このテストは失敗するはずです。

テストケースをテストスイートに追加すると、他のテストと一緒に実行できるようになります。次のステップは、テストスイートを実行することです。

テストの実行 およびカバレッジ

BeeWareは、テストプロセスの管理にtoxを使用し、独自のテストスイートにはpytestを使用しています。

デフォルトの tox コマンドには、以下の実行が含まれます：

• プレコミットフック
• towncrier リリースノートの確認

• ドキュメントのリンティング

• 利用可能なPythonバージョン向けのテストスイート

• コードカバレッジレポート

これは、プルリクエストを送信した際にCIによって実行される処理の要約です。

テストスイート全体を実行するには、次のコマンドを実行してください：

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

(.venv) C:\...>tox

テストスイート全体の実行には時間がかかる場合があります。tox を並列実行するか、tox p（または tox run-parallel）を実行することで、実行速度を大幅に上げることができます。テストスイートを並列実行すると、実行中の進捗状況に関するフィードバックは少なくなりますが、テスト実行終了時には検出された問題の概要が表示されます。テストが実行されたことを示す何らかの出力が表示されるはずです。 SKIPPED テストが表示されることはありますが、FAIL や ERROR といったテスト結果が表示されることは決してありません。私たちは、パッチをマージする前に毎回、完全なテストスイートを実行しています。その過程で問題が発見された場合、そのパッチはマージされません。もしテストエラーや失敗が見つかった場合は、テスト環境に何か異常があるか、あるいは私たちがこれまで遭遇したことのないエッジケースを発見したかのどちらかです。いずれにせよ、ぜひお知らせください！

テストが成功したことに加え、100%のテストカバレッジが報告されるはずです。

テストのバリエーションを実行する

複数のPythonバージョンでテストを実行する

デフォルトでは、多くのtoxコマンドは、BeeWareがサポートする各Pythonバージョンに対して1回ずつ、テストスイートを複数回実行しようとします。ただし、これを行うには、各Pythonバージョンがマシンにインストールされており、toxのPython 検出プロセスから利用可能である必要があります。一般的に、PATH経由でPythonのバージョンが利用可能であれば、toxはそのバージョンを見つけて使用できるはずです。

テストスイートのみを実行する

新機能の開発で迅速に反復開発を行っている場合、テストスイート全体を実行する必要はなく、ユニットテストのみを実行すれば十分です。これを行うには、次のコマンドを実行します：

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

(.venv) C:\...>tox -e py

テストの一部を実行する

デフォルトでは、tox はユニットテストスイート内のすべてのテストを実行します。新しいテストを開発している際、そのテストを「そのテストだけ」実行したい場合があるかもしれません。その場合は、pytest の引数として [任意の (https://docs.pytest.org/en/latest/how-to/usage.html#specifying-which-tests-to-run) 指定子]tox を渡すことで実現できます。これらのテストパスは briefcase ディレクトリを基準としています。たとえば、単一のファイル内のテストのみを実行するには、次のように実行します：

macOSLinuxWindows

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py

テストスイートの一部を実行しても、カバレッジレポートは表示されますが、カバレッジの結果には、実行した特定のテストによって実行されたコード行のみが報告されます。

特定のPythonバージョンに対してテストスイートを実行する

デフォルトでは、tox -e py は、お使いのマシン上で python として解決されるインタープリタを使用して実行されます。複数の Python バージョンがインストールされており、インストール済みのバージョンの中から特定の Python バージョンでテストを実行したい場合は、使用する Python バージョンを指定することができます。たとえば、Python 3.10 でテストスイートを実行するには、次のように実行します：

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

(.venv) C:\...>tox -e py310

コマンドラインに -- とテスト仕様を追加することで、テストのサブセット を実行できます。

カバレッジを計測せずにテストスイートを実行する（高速）

デフォルトでは、tox は pytest スイートをシングルスレッドモードで実行します。テストスイートを並列で実行することで、実行速度を向上させることができます。このモードでは、生成されたプロセス内でのカバレッジの取得が複雑なため、カバレッジファイルは生成されません。単一の Python バージョンを「fast」モードで実行するには、次のように実行してください：

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

(.venv) C:\...>tox -e py-fast

コマンドラインに -- とテスト仕様を追加することで、テストのサブセット を実行できます。また、テストターゲットにバージョンを追加することで、特定の Python バージョン を使用できます（例：Python py310-fast で高速に実行するには 3.10 を指定します）。

コードカバレッジ

BeeWareは、コードベースにおいて100%のテストカバレッジを維持しています。プロジェクトにコードを追加または変更する際は、変更箇所を確実にテストできるよう、テストコードを追加する必要があります。

ただし、BeeWareは複数のプラットフォームおよび複数のPythonバージョンを対象としているため、単一のプラットフォームやPythonバージョンでは完全なカバレッジを検証することはできません。 この問題に対処するため、tool.coverage.coverage_conditional_plugin.rules の pyproject.toml セクションにはいくつかの条件付きカバレッジルールが定義されています（例えば、no-cover-if-is-windows を使用すると、Windows でテストスイートを実行した際に実行されないコードブロックをマークできます）。これらのルールは、特定のプラットフォームや Python バージョンでのみカバレッジが確保されているコードのセクションを特定するために使用されます。

なお、Pythonのバージョンが異なる場合、カバレッジレポートには若干の不整合が生じることがあります。例えば、カバレッジファイルをあるバージョンのPythonで生成したものの、レポート作成を別のバージョンで行った場合、レポートには未検出の分岐に関する誤検知が含まれる可能性があります。このため、カバレッジレポートを作成する際は、常にカバレッジファイルの生成に使用したPythonのバージョンの中で最も古いバージョンを使用するようにしてください。

保険適用範囲の結果の理解

カバレッジテストの出力の最後には、収集されたカバレッジデータのレポートが表示されるはずです：

名称    残高   未決済   ブランチ・ブランチ・パート   カバー   欠落
 ---------------------------------------------------
 合計    7540 0   1040 0  100.0%

これは、テストスイートがコード内のあらゆる分岐パスを網羅して実行したことを示しています。これはバグが一切ないことを100％保証するものではありませんが、コードベース内のすべての行が実行されていることを意味します。

コードベースに変更を加えると、カバレッジに穴が生じる可能性があります。その場合、カバレッジレポートには、どの行が実行されていないかが表示されます。例えば、some/interesting_file.pyに変更を加えて新しいロジックを追加したとします。その場合のカバレッジレポートは、次のようなものになるでしょう：

名前 ステートメント数   ミス   分岐   BrPart  カバレッジ   欠落
 -------------------------------------------------------------------------------
 src/some/interesting_file.py 111 1     26 0  98.1%   170, 302-307, 320->335
 -------------------------------------------------------------------------------
 合計 7540 1   1726 0  99.9%

これは、170行目、302行目から307行目、および320行目から335行目への分岐が、テストスイートによって実行されていないことを示しています。このカバレッジを回復するには、新しいテストを追加するか、既存のテストを修正する必要があります。

ホストプラットフォームおよびPythonバージョンの対応状況レポート

お使いのプラットフォームおよびPythonのバージョンに対応したカバレッジレポートを生成できます。たとえば、Python 3.10 でテストスイートを実行し、カバレッジレポートを生成するには、次のように実行します：

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

(.venv) C:\...>tox -m test310

ホストプラットフォームの対応状況レポート

tox でサポートされているすべての Python バージョンが利用可能な場合、ホストプラットフォームのカバレッジは次のコマンドを実行することで報告できます：

macOSLinuxWindows

(.venv) $ tox p -m test-platform

(.venv) $ tox p -m test-platform

(.venv) C:\...>tox p -m test-platform

HTML形式でのカバレッジレポート

カバレッジ環境名の末尾に -html を付けることで、HTML 形式のカバレッジレポートを生成できます。例えば：

macOSLinuxWindows

(.venv) $ tox -e coverage-platform-html

(.venv) $ tox -e coverage-platform-html

(.venv) C:\...>tox -e coverage-platform-html

テストを書くことだけが目的ではありません！

私たちはすべてのコードを確実にテストしていますが、その任務は単にそのレベルのテストを維持することだけではありません。その任務の一部は、開発を進めながらコードを監査することにもあります。コンクリート製の救命胴衣のために包括的なテストスイートを作成することは可能でしょう……しかし、コンクリート製の救命胴衣は、本来の目的を果たすには依然として役に立たないのです！

テストを開発する際は、コアモジュールが内部的に一貫性を持っているかどうかも確認するようにしてください。 もし、メソッド名に内部的な一貫性がない場合（例：あるモジュールではon_selectという名前なのに、別のモジュールではon_selectedという名前になっているなど）、あるいはデータの扱いに一貫性がない場合を見つけたら、それをマークし、チケットを立てて私たちに知らせてください。あるいは、どう修正すべきか確信がある場合は、見つけた問題を修正するプルリクエストを作成してください。

すべてが正常に動作したら、変更内容を含むプルリクエストを送信できます。