mastra-smoke-test

Mastra スモークテスト

Mastra プロジェクトの包括的なスモークテストです。

リリースのスモークテストワークフロー

段階的に情報を確認してください。ワークフローが分岐するまではこのファイルを参照し、分岐したら現在の分岐に対応するリファレンスだけを読みます。全体像が必要な場合は、簡潔な一覧である references/release-smoke.md を参照してください。

アルファリリースの分岐点

アルファのスモークテストを行う前に、アルファのバージョニング PR の状態を確認してください。標準の Changesets リリースブランチを優先してください。

gh pr view changeset-release/main \
  --json number,title,state,url,headRefName,baseRefName,isDraft,mergeable,reviewDecision,updatedAt,mergedAt,mergeCommit

想定される形式：

title: chore: version packages (alpha)
head: changeset-release/main
base: main

ブランチの検索に失敗した場合は、オープン中および最近マージされた PR を検索してください。

gh pr list --state open --search 'version packages alpha in:title' --limit 20
gh pr list --state merged --search 'version packages alpha in:title' --limit 20

次に、状態に応じて分岐します。

• バージョニング PR がオープンの場合は、references/alpha-versioning-pr.md を読みます。
• バージョニング PR がマージ済みの場合は、references/alpha-publish.md を読みます。
• バージョニング PR が存在しない場合は、その旨を報告し、予定されているアルファのバージョニングフローまたはユーザーの指示を待ちます。

自動アルファ公開ワークフローが完了し、対象のパッケージをインストールできるようになるまで、アルファのスモークテスト用プロジェクトを作成しないでください。

安定版リリースの分岐点

ユーザーが安定版／フルリリースのワークフローを実行する場合は、references/stable-release-smoke.md を読みます。パッケージの一部が公開された後にそのワークフローが失敗した場合は、references/stable-partial-publish-recovery.md に切り替えます。

対象範囲と対象を絞ったチェック

リリースパッケージの公開後、スモークテストの実行前に、references/release-scope-discovery.md を読み、変更された機能を特定します。ベースラインのチェックリストにはデフォルトの生成プロジェクトを使用し、生成プロジェクトで検証されない変更機能には対象を絞ったチェックを追加してください。

対象範囲の調査で分岐が特定された場合：

• 変更機能を全般的にカバーするには、references/targeted-feature-smoke.md を読みます。
• ストレージ／プロバイダーのスキーマやマイグレーションの変更については、references/storage-provider-migration-smoke.md を読みます。

⚠️ 必須テストチェックリスト

進捗の記録には task_write を使用してください。 --test で指定されていない限り、すべてのテストを実行します。

実際のブロッカーに遭遇しない限り、テストを省略しないでください。 「複雑そうだった」や「確信がなかった」は正当な理由ではありません。すべてを試してください。文字どおり続行できない場合にのみテストを中止してください。試したことと、続行を妨げた要因を報告してください。

#	テスト	リファレンス	必須となる条件
1	セットアップ	references/tests/setup.md	常に
2	エージェント	references/tests/agents.md	--test agents またはフル実行
3	ツール	references/tests/tools.md	--test tools またはフル実行
4	ワークフロー	references/tests/workflows.md	--test workflows またはフル実行
5	トレース	references/tests/traces.md	--test traces またはフル実行
6	スコアラー	references/tests/scorers.md	--test scorers またはフル実行
7	メモリー	references/tests/memory.md	--test memory またはフル実行
8	MCP	references/tests/mcp.md	--test mcp またはフル実行
9	エラー	references/tests/errors.md	--test errors またはフル実行
10	実験	references/tests/experiments.md	--test experiments またはローカルでのフル実行
11	Studio デプロイ	references/tests/studio.md	--test studio（クラウドのみ）
12	サーバーデプロイ	references/tests/server.md	--test server（クラウドのみ）

ステージング環境および本番環境でのフル実行では、コンパニオンワーカーがローカルビルド成果物であるため、該当しない実験は省略します。そのため、--test experiments を対象に絞って実行する場合は、--env local が必要です。

実行フロー

1. 実行する各テストのリファレンスファイルを読む
2. そのリファレンスファイルの手順を実行する
3. 次に進む前に、テストを完了としてマークする

部分テスト（--test）

--test が指定された場合：

1. 常に セットアップ（ステップ 1）を実行します
2. 指定されたテスト のみ を実行します
3. それ以外のテストはスキップします

例：--test agents,traces → ステップ 1、2、5 のみを実行します。

ローカル Studio のブラウザースモークテスト

ローカルリリースのスモークテストでは、--skip-browser が明示的に指定されている場合、またはブラウザーへのアクセスが実際にブロックされている場合を除き、API／curl の確認と Studio のブラウザーチェックの両方を実施してください。API の確認ではランタイムのエンドポイントが動作することを検証し、ブラウザーの確認では Playground／Studio UI が読み込まれ、フォームを送信でき、結果が表示されることを検証します。

ブラウザーを開く前に：

1. 開発サーバーが想定されるポートで稼働していることを確認します：

   curl -s -o /dev/null -w '%{http_code}\n' http://localhost:4111
   lsof -i :4111 || true
   

2. プロセスが停止していた場合は、生成されたプロジェクトから再起動し、準備が整うまで待ちます：

   cd "$SMOKE_DIR/smoke-project"
   pnpm run dev > "$SMOKE_DIR/logs/dev-server-browser.log" 2>&1 &
   
   for i in {1..60}; do
     code=$(curl -s -o /dev/null -w '%{http_code}' http://localhost:4111 || true)
     [ "$code" = 200 ] && break
     sleep 1
   done
   

3. ブラウザーツールを使って http://localhost:4111 に移動します。networkidle がタイムアウトしても domcontentloaded が成功し、UI が使用可能であれば、そのまま続行してタイムアウトを記録します。

推奨するブラウザータスクリスト：

1. Verify Studio shell loads
2. Smoke test agent chat UI
3. Smoke test tools UI
4. Smoke test workflows UI
5. Smoke test observability, scorers, and MCP pages
6. Report browser smoke results

次のページを確認します：

領域	ルート	確認内容
Studio シェル	/ または /agents	サイドバー／ナビゲーションが表示されること、Mastra のバージョンが表示されること、クラッシュ／エラーオーバーレイがないこと
エージェント	/agents → エージェントチャット	エージェント一覧に想定されるエージェントが表示されること、チャット入力欄が表示されること、What's the weather in Tokyo? の送信に対して一貫性のある応答が返り、想定される場合はツール呼び出しのバッジ／結果が表示されること
ツール	/tools → ツール詳細	ツール一覧に get-weather が表示されること、入力フォームが表示されること、Paris などの都市を送信すると、天気のフィールドを含む JSON の結果が表示されること
ワークフロー	/workflows → ワークフロー詳細	ワークフロー一覧に weather-workflow が表示されること、グラフ／詳細が表示されること、Berlin などの都市で実行すると success として完了すること、ステップにタイミング／出力コントロールが表示されること
トレース	/observability	最近のエージェント／ワークフローのトレースが表示されること。ブラウザーチェック中に実行されたものも含みます
スコアラー	/scorers	登録済みのスコアラーが名前／説明とともに表示されること。例：Tool Call Accuracy、Completeness、Translation Quality
MCP	/mcps	ページが読み込まれること。デフォルトのテンプレートでは、空の状態（No MCP Servers yet）は合格です

ブラウザー操作でアクセシビリティスナップショットに十分なテキストが表示されない場合は、document.body.innerText を確認するか、スクリーンショットを撮影して、画面上で確認できた証拠を記録します。ブラウザースモークテストでは、API の出力だけに頼らないでください。

ブラウザーの結果を、たとえば次のような独立したセクションとして $SMOKE_DIR/smoke-report.md に追記します：

## Studio Browser Smoke Results

| Area         | Result | Evidence                                                          |
| ------------ | ------ | ----------------------------------------------------------------- |
| Studio shell | PASS   | Browser loaded localhost:4111; sidebar/nav visible; version shown |
| Agents UI    | PASS   | Weather Agent chat returned Tokyo weather and displayed tool call |
| Tools UI     | PASS   | get-weather form returned Paris weather JSON                      |
| Workflows UI | PASS   | weather-workflow Berlin run completed as success                  |
| Traces UI    | PASS   | Recent agent/workflow traces listed                               |
| Scorers UI   | PASS   | Expected scorers listed                                           |
| MCP UI       | PASS   | Expected empty MCP state shown                                    |

ブラウザースモークテストがローカル Studio のみを対象としたものか、クラウド Studio／デプロイ済みサーバーも対象としたものかを、分けて明記してください。

---

使用方法

# Full smoke test
smoke test --env local --existing-project ~/my-app
smoke test --env staging -d ~/projects -n test-app

# Partial testing
smoke test --env local --existing-project ~/my-app --test agents
smoke test --env production --existing-project ~/my-app --test studio,server,traces

# Multi-environment: same project, different targets
smoke test --env staging --existing-project ~/my-app   # Uses .mastra-project-staging.json
smoke test --env production --existing-project ~/my-app # Uses .mastra-project.json

複数環境のサポート

1 つのプロジェクトで、設定ファイルを分けることで、すべての環境を対象にできます：

環境	設定ファイル	動作
ローカル	N/A	pnpm dev → localhost:4111
ステージング	.mastra-project-staging.json	staging.mastra.cloud にデプロイします
本番	.mastra-project.json	mastra.cloud にデプロイします

セットアップの詳細については、references/tests/setup.md を参照してください。

パラメーター

パラメーター	必須	デフォルト	説明
--env	はい	-	local、staging、production
--directory	*	~/mastra-smoke-tests	新規プロジェクトの親ディレクトリ
--name	*	-	プロジェクト名
--existing-project	*	-	既存プロジェクトへのパス
--tag	いいえ	latest	バージョンタグ（例：alpha）
--pm	いいえ	pnpm	パッケージマネージャー
--llm	いいえ	openai	LLM プロバイダー
--db	いいえ	libsql	ストレージ：libsql、pg、turso
--test	いいえ	（すべて）	実行する特定のテスト
--browser-agent	いいえ	false	ブラウザーエージェントを追加
--skip-browser	いいえ	false	curl のみ（ブラウザー UI なし）
--byok	いいえ	false	独自のキーを持ち込むテスト

* --directory + --name、または --existing-project のいずれかが必要です

テストオプション（--test）

オプション	説明	環境
agents	エージェントページとチャット	すべて
tools	ツールページと実行	すべて
workflows	ワークフローページと実行	すべて
traces	可観測性／トレース	すべて
scorers	評価／スコアラーページ	すべて
memory	会話の永続化	すべて
mcp	MCP サーバーページ	すべて
errors	エラー処理	すべて
experiments	実験ワーカープロトコル	ローカル
studio	Studio のデプロイのみ	クラウド
server	サーバーのデプロイのみ	クラウド

前提条件

すべての環境：

• Node.js とパッケージマネージャー
• 環境変数または .env に LLM API キー

ローカル（--env local）：

• ブラウザーツールを有効化（/browser on）

クラウド（--env staging/production）：

• Mastra プラットフォームのアカウント

クイックスタートの流れ

1. Setup      → Read references/tests/setup.md, create/verify project
2. Start      → `pnpm run dev` (local) or deploy (cloud)
3. Test       → For each test, read its reference file and execute
4. Verify     → Check all items in reference file's checklist
5. Report     → Summarize pass/fail for each test

参照

ファイル	用途
references/tests/*.md	各必須テストの詳細な手順
references/release-smoke.md	リリーススモークテストの簡易参照インデックス
references/alpha-versioning-pr.md	オープン中のアルファバージョニング PR の準備状況
references/alpha-publish.md	マージ済みのアルファ PR の公開確認
references/stable-release-smoke.md	安定版の公開と最終スモークテスト
references/stable-partial-publish-recovery.md	安定版の部分公開からの復旧
references/release-scope-discovery.md	リリース PR の対象範囲の調査と計画
references/targeted-feature-smoke.md	変更された機能を対象とするスモークテストのパターン
references/storage-provider-migration-smoke.md	ストレージ／プロバイダー移行のスモークテストパターン
references/local-setup.md	ローカル開発サーバーのセットアップ
references/cloud-deploy.md	クラウドデプロイの詳細
references/cloud-advanced.md	BYOK、ストレージのテスト
references/common-errors.md	トラブルシューティング
references/gcp-debugging.md	インフラストラクチャのデバッグ
references/architecture.md	スモークテストのアーキテクチャに関するメモ
references/environment-variables.md	環境変数のセットアップ
scripts/test-server.sh	サーバー API テストスクリプト
scripts/discover-release-scope.sh	リリース PR の対象範囲の調査
scripts/check-versioning-pr.sh	アルファバージョニング PR のスポットチェック用ヘルパー

プラットフォームのダッシュボード

• 本番環境：https://projects.mastra.ai
• ステージング：https://projects.staging.mastra.ai

Gateway API のテスト（メモリ、スレッド、Gateway 経由の BYOK）には、platform-smoke-test を使用してください。

結果の報告

テスト後、次の内容を報告してください。

## Smoke Test Results

**Environment**: local/staging/production
**Project**: <name>

| Test   | Status | Notes |
| ------ | ------ | ----- |
| Setup  | ✅/❌  |       |
| Agents | ✅/❌  |       |
| Tools  | ✅/❌  |       |
| ...    |        |       |

**Issues Found**: (list any)
**Warnings**: (list any deploy/runtime warnings)
**Skipped Tests**: (list with reason - e.g., "Server Deploy - not applicable in local environment")