temporal-python-testing

temporal-python-testingスキルの概要

temporal-python-testingスキルでできること

temporal-python-testingスキルは、単なる汎用的な pytest サンプルを書くためのものではなく、Temporal Python ワークフロー向けに信頼性の高いテストを設計し、実行するのに役立ちます。特に、ワークフロー中心のシステムを構築していて、素早いフィードバック、安全なリファクタリング、そしてワークフローコードの determinism を保てているという確信が必要なチームに向いています。

どんな人に向いているか

このスキルが特に合うのは、次のようなケースです。

• すでに Temporal を使っている Python 開発者
• ワークフローコードにテストカバレッジを追加したいチーム
• flaky な Temporal テストの原因を追っているエンジニア
• デプロイ前のワークフロー変更をレビューする担当者
• 場当たり的なプロンプト助言ではなく、temporal-python-testing for Test Automation が必要な人

一方で、まだワークフローエンジンの選定段階にいる場合や、プロジェクトで Temporal Python SDK を使っていない場合には、有用性は下がります。

このスキルが本当に解決する仕事

多くのユーザーが欲しいのは、単に「テストを書くこと」ではありません。実際には、次のような現場の疑問にすばやく答えたいはずです。

• 実時間を待たずにワークフローロジックをどうテストするか？
• activity はいつモックし、いつ worker を使った厚めのテストを回すべきか？
• ワークフロー変更をデプロイする前に、どうやって determinism を確認するか？
• 開発環境と CI の両方で、安定してテストを回すにはどんなローカルセットアップが必要か？

temporal-python-testing skill の価値は、こうした判断をテスト種別ごとに整理してくれる点にあります。具体的には、time-skipping を使う unit testing、activity をモックする integration testing、互換性確認のための replay testing、そしてローカル環境構築のガイドです。

汎用的な Temporal プロンプトと何が違うのか

通常のプロンプトでもサンプルコードは出せますが、このスキルはテスト戦略をより明確に示してくれます。

• Temporal 固有のテスト境界を中心に据えている
• integration test をデフォルトの主力として押し出している
• 汎用回答では抜けがちな replay testing を含んでいる
• 1 枚の巨大ドキュメントではなく、目的別のリソースファイルを案内している

そのため、導入判断の材料としても、チームでワークフローのテスト方針を標準化したい場合にも使いやすくなっています。

判断前に読むべきファイル

temporal-python-testing を評価するなら、まずは次のファイルを確認してください。

1. SKILL.md
2. resources/unit-testing.md
3. resources/integration-testing.md
4. resources/replay-testing.md
5. resources/local-setup.md

この順番は、実際の導入フローにも沿っています。まず高速なローカルテスト、次にオーケストレーションのテスト、最後にデプロイ安全性の確認という流れです。

temporal-python-testingスキルの使い方

temporal-python-testingのインストール方法

wshobson/agents リポジトリからインストールします。

npx skills add https://github.com/wshobson/agents --skill temporal-python-testing

このリポジトリでは plugins/backend-development/skills/temporal-python-testing 配下に格納されているため、インストール後はツールからその repo path にアクセスできることを確認してください。

初回利用でおすすめの読み進め方

最初から全部読む必要はありません。まずは次の順番がおすすめです。

1. SKILL.md を読んで、対象範囲とテスト方針をつかむ
2. 直近の目的が高速なワークフローテストなら resources/unit-testing.md を開く
3. activity のモックや worker ベースのテストが必要なら resources/integration-testing.md を開く
4. すでに実行中の workflow に影響するコードを変える前に resources/replay-testing.md を読む
5. 課題がテスト設計ではなく環境構築なら resources/local-setup.md を見る

この流れにすると、Temporal テストでありがちな「選択肢が多すぎて迷う」状態を避けやすくなります。

このスキルに渡すべき入力情報

temporal-python-testing usage の質は、こちらが渡す情報の具体性に大きく左右されます。少なくとも次は含めるべきです。

• workflow class 名
• activity 名とその副作用
• テスト種別が unit / integration / replay のどれか
• 現在のスタック: pytest, temporalio, Docker, local Temporal server
• 失敗の種類: timeout、nondeterminism、mock setup、worker registration、flaky assertions
• 欲しい確信度: ローカル開発用、CI 用、デプロイ前の互換性確認用

ここが曖昧だと、どうしても出力は汎用的な内容に寄りがちです。

ざっくりした要望を良いプロンプトに変える

弱いプロンプト:

• “Help me test a Temporal workflow in Python.”

より良いプロンプト:

• “Use the temporal-python-testing skill to propose pytest tests for a Temporal Python workflow that waits on timers, calls two activities, and must stay deterministic across deployments. I want a fast local test, an integration test with mocked activities, and guidance on replay testing before release.”

最も良いプロンプト:

• “Use the temporal-python-testing skill. I have OrderWorkflow.run(order_id) that sleeps for retries, calls charge_card and send_receipt, and currently fails in CI. Generate a test plan using pytest async fixtures, WorkflowEnvironment.start_time_skipping(), mocked activity patterns where appropriate, and a replay testing step for deployment safety. Explain what should be unit tested versus integration tested.”

強いプロンプトほど出力の質がはっきり上がります。理由は、このスキルを正しいテストモードに明確に乗せられるからです。

このスキルが想定している主要な使い方

リポジトリの内容を見ると、実務上の使い道は大きく 4 つに分かれます。

temporal-python-testingでの unit testing

ワークフローの挙動、timer、分岐ロジックに対して素早くフィードバックが欲しいときに使います。このスキルでは WorkflowEnvironment.start_time_skipping() を案内しており、長い待ち時間も即座に完了させられます。

temporal-python-testingでの integration testing

worker registration やワークフローのオーケストレーションを実際に動かしつつ、外部 activity の挙動はモックしたい場合に使います。大半のワークフローロジックに対して、これが推奨されるデフォルトのテスト手法です。

temporal-python-testingでの replay testing

すでに動いている execution に影響する可能性があるワークフローコード変更を出荷する前に使います。本番安全性の観点では、ここが最も価値の高い部分です。

temporal-python-testingでの local setup

本当の詰まりどころが、Temporal server、UI、pytest 環境を安定して立ち上げることにある場合に使います。

このスキルが暗に推しているテスト戦略

temporal-python-testing guide は、テスト戦略について中立ではありません。明確に次を優先しています。

• integration test を中心に据える
• unit test は分離しやすいワークフロー挙動や activity ロジックに使う
• end-to-end test は限定的に使う
• replay test を後方互換性と determinism の確認に使う

この偏りはむしろ実用的です。遅くて壊れやすい end-to-end テスト群に投資しすぎるのを防げます。

実運用での導入前提と依存関係

このスキル自体はドキュメント中心ですが、前提としてプロジェクト側で次を扱える必要があります。

• pytest を使う Python プロジェクト
• Temporal Python SDK の利用
• async テスト実行
• テスト内での worker セットアップ
• 開発環境や CI で使う、Docker ベースの local Temporal stack（任意）

リソースファイルを見る限り、ローカルセットアップでは Docker Compose で Temporal、Postgres、Temporal UI を立ち上げる構成が一般的です。チームとしてローカルや CI で Docker を使えないなら、その制約は早めに判断してください。どこまでこのスキルをそのまま採用できるかが変わります。

依頼できる成果物の例

良い temporal-python-testing usage の依頼例は次のようなものです。

• “Generate a pytest fixture for time-skipping workflow tests.”
• “Show how to mock activities in a worker-based integration test.”
• “Design replay tests for multiple stored workflow histories.”
• “Recommend a split between unit, integration, and end-to-end tests for this workflow.”
• “Help debug a nondeterminism failure after refactoring a workflow.”

抽象的に “test examples” を求めるより、こうした頼み方のほうがずっと有効です。

出力の質をすぐ上げるコツ

• テストしたい workflow entrypoint を明示する
• activity をモックにするか実物にするか伝える
• timer、retry、signal、長時間待機の有無を書く
• その workflow に本番履歴がすでにあるか伝える
• replay や worker startup が失敗しているなら現在のエラー出力を添える

Temporal のテスト課題は、たいてい文法ではなく境界の置き方にあります。境界を明確に説明するほど、このスキルは役立ちます。

このスキルが最も時間を節約する場面

最大の価値は、定型コードの自動生成ではありません。よくある間違った進み方を避けられることです。

• end-to-end test しか書かない
• timer の多い workflow で time-skipping を使わない
• モックしすぎる、またはモックが足りない
• workflow 変更前に replay testing を省く
• ローカル環境の問題とテスト設計の問題を混同する

もしこれが今のチームの悩みに近いなら、temporal-python-testing install は十分検討に値します。

temporal-python-testingスキル FAQ

temporal-python-testingは初心者にも向いていますか？

はい、ただし pytest と Temporal の基本をすでに理解しているなら、です。両方ともまったく初めてなら向きません。このスキルは、workflow、activity、worker、async Python を理解し、テストをどのレイヤーに置くべきか判断できることを前提にしています。

Temporal のテストコードを LLM に直接聞くより良いですか？

実プロジェクトではたいていその通りです。汎用プロンプトは、determinism、replay validation、time-skipping といった Temporal 固有の論点を見落としがちです。手早いサンプルコードより正しさが重要なら、temporal-python-testing skill のほうが向いています。

replay testing 専用の支援はありますか？

あります。これは temporal-python-testing を使う強い理由の 1 つです。リポジトリには、記録済み event history に対してワークフロー変更を検証するための resources/replay-testing.md が用意されています。

どんな場合は temporal-python-testing を使わないほうがいいですか？

次のケースでは見送って構いません。

• Temporal Python を使っていない
• ただの簡単な pytest 復習だけで足りる
• 課題がワークフロー挙動ではなく、一般的な mocking にある
• テスト方針より本番アーキテクチャ設計の助言が必要

専門特化していることは、この問題設定に合うときだけ強みになります。

ローカルの Temporal セットアップも扱っていますか？

はい。resources/local-setup.md には、local Temporal server、Postgres、UI を Docker Compose で構築するパターンが含まれています。より実環境に近い開発環境が必要なテストでは、ここが重要です。

主に unit test 向けのスキルですか？

いいえ。元の内容では、integration test を主軸に据え、unit test と end-to-end test はより選択的に使う方針が明示されています。チームが分離された unit test だけを求めているなら、このスキルの一部しか使わないことになります。

temporal-python-testingはCIでも役立ちますか？

はい。特に次の用途で有効です。

• workflow テストスイートの自動化
• カバレッジを意識したテスト戦略
• デプロイ前の replay check
• マシン差を減らす一貫した環境構築

このスキル自体に CI スクリプトは含まれませんが、CI パイプラインに運用へ落とし込めるテストパターンは提供してくれます。

temporal-python-testingスキルを改善するには

必要なテスト種別を最初に明示する

temporal-python-testing からより良い結果を得る最短ルートは、自分がどのレーンにいるか最初に伝えることです。

• unit test
• integration test
• replay test
• local setup/debugging

ここを決めないままだと、回答が複数のパターンを混ぜてしまい、かえって手戻りが増えます。

アーキテクチャの要約ではなく、workflow 固有の情報を出す

悪い入力:

• “We have a Temporal-based order system.”

より良い入力:

• “OrderWorkflow waits for payment confirmation, retries every hour, calls charge_card, and emits a receipt activity. We need tests for timeout handling and replay safety after refactoring retry logic.”

この差は大きいです。timer の挙動、activity のオーケストレーション、互換性の懸念がすべて明示されるため、回答の精度が上がります。

何がすでに失敗しているのかを伝える

このスキルがより正確に役立つ代表的な失敗パターンは次の通りです。

• コード変更後の workflow nondeterminism
• worker が想定した activity または workflow を登録していない
• mocked activity の assertion が発火しない
• 長時間 timer のせいでテストが遅い
• ローカルの Temporal 環境が正常に起動しない
• unit と integration のどちらでテストすべきか判断できない

欲しい最終形だけでなく、まず今の失敗から話し始めるのが効果的です。

リソースファイルは選んで使う

よくある失敗は、このスキル全体を 1 つのドキュメントとして扱ってしまうことです。実際には次の使い分けが適しています。

• resources/unit-testing.md は time-skipping fixture と分離しやすい挙動の検証に使う
• resources/integration-testing.md はモック主導のオーケストレーションテストに使う
• resources/replay-testing.md はデプロイ安全性の確認に使う
• resources/local-setup.md は環境問題が実行のボトルネックになっているときだけ使う

こうするとコンテキストのノイズが減り、生成される支援内容の関連性が高まります。

コードだけでなく、トレードオフも聞く

強い temporal-python-testing guide プロンプトは、テストレイヤーの理由づけまで求めます。

• なぜこれは unit test ではなく integration test なのか？
• どの activity はモックし、どれは実物のままにすべきか？
• どんなコード変更で replay testing が必要になるのか？
• CI に入れるべきものとローカル専用チェックは何か？

こうした問いは、単なるコード断片よりも長持ちするテスト戦略につながります。

現実的な制約を入れてプロンプトを改善する

次のような制約を明示してください。

• CI の実行時間制限
• 開発者マシンでは Docker が使えない
• production history を取得できるかどうか
• カバレッジ目標を達成する必要がある
• 外部依存が flaky
• 複数 workflow が activity を共有している

制約があることで、このスキルは実際に採用可能なパターンを提案しやすくなります。

最初の出力のあとにもう一段深掘りする

最初の回答のあと、次のような追い質問で精度を上げられます。

• “Convert this into pytest fixtures.”
• “Reduce this to the minimum deterministic test set.”
• “Show where to use mocked activities versus real ones.”
• “Add replay testing for existing workflow histories.”
• “Rewrite for our exact workflow names and task queues.”

最初の回答は戦略のたたき台にとどまることが多く、temporal-python-testing skill が実装可能なレベルになるのは、2 回目のやり取りからです。

導入時に陥りやすい最大の落とし穴に注意する

最大の落とし穴は、1 つのテストスタイルですべてを解決しようとすることです。Temporal のコードには通常、次の組み合わせが必要です。

• workflow ロジック向けの高速な time-skipping test
• オーケストレーションへの信頼を得る integration test
• 安全に進化させるための replay test

このレイヤー分けを前提にスキルを使うと、出力ははるかに実務向きになり、本番ニーズにも近づきます。