smoke-test

スモークテストスキル

create-mastra@<tag> を使用して新しい Mastra プロジェクトを作成し、Chrome で Mastra Studio のスモークテストを実行します。

このスキルは、Chrome MCP サーバーを使用する Claude Code 向けです。 ブラウザツールが組み込まれた MastraCode を使用する場合は、代わりに mastracode-smoke-test を使用してください。

使用方法

/smoke-test --directory <path> --name <project-name> --tag <version> [--pm <package-manager>] [--llm <provider>]
/smoke-test -d <path> -n <project-name> -t <version> [-p <package-manager>] [-l <provider>]

パラメーター

パラメーター	短縮形	説明	必須	デフォルト
--directory	-d	プロジェクトを作成する親ディレクトリ	はい	-
--name	-n	プロジェクト名（サブディレクトリとして作成されます）	はい	-
--tag	-t	create-mastra のバージョンタグ（例：latest、alpha、0.10.6）	はい	-
--pm	-p	パッケージマネージャー：npm、yarn、pnpm、または bun	いいえ	npm
--llm	-l	LLM プロバイダー：openai、anthropic、groq、google、cerebras、mistral	いいえ	openai

例

# Minimal (required params only)
/smoke-test -d ~/projects -n my-test-app -t latest

# Full specification
/smoke-test --directory ~/projects --name my-test-app --tag alpha --pm pnpm --llm anthropic

# Using short flags
/smoke-test -d ./projects -n smoke-test-app -t 0.10.6 -p bun -l openai

ステップ 0：パラメーターの検証（最初に必ず実行）

重要：続行する前に、ARGUMENTS を解析して検証してください。

1. 上記で指定された ARGUMENTS 文字列から引数を解析します
2. 必須パラメーターを確認します：
   • --directory または -d：必須。不足している場合は失敗とします
   • --name または -n：必須。不足している場合は失敗とします
   • --tag または -t：必須。不足している場合は失敗とします
3. オプションのパラメーターにデフォルト値を適用します：
   • --pm または -p：指定されていない場合は npm をデフォルトにします
   • --llm または -l：指定されていない場合は openai をデフォルトにします
4. 値を検証します：
   • pm は npm、yarn、pnpm、bun のいずれかである必要があります
   • llm は openai、anthropic、groq、google、cerebras、mistral のいずれかである必要があります
   • directory は存在している必要があります（存在しない場合は作成されます）
   • name は有効なディレクトリ名である必要があります（スペースや特殊文字は使用できません）

検証に失敗した場合：処理を停止し、不足または無効なパラメーターを示して使用方法のヘルプを表示します。

-h または --help が渡された場合：この使用方法の情報を表示して終了します。

前提条件

このスキルでは、ブラウザーを自動化するために Chrome MCP サーバー（Claude-in-Chrome）が必要です。設定され、実行中であることを確認してください。

Chrome MCP サーバーは、tabs_create_mcp、tabs_context_mcp、navigate_mcp、click_mcp、type_mcp、screenshot_mcp などのツールを提供します。

実行手順

ステップ 1：Mastra プロジェクトを作成する

対話型プロンプトを避けるため、明示的なパラメーターを指定して create-mastra コマンドを実行します。

# For npm
npx create-mastra@<tag> <project-name> --no-git --llm <llmProvider> --timeout 120000

# For yarn
yarn dlx create-mastra@<tag> <project-name> --no-git --llm <llmProvider> --timeout 120000

# For pnpm
pnpm create mastra@<tag> <project-name> --no-git --llm <llmProvider> --timeout 120000

# For bun
bunx create-mastra@<tag> <project-name> --no-git --llm <llmProvider> --timeout 120000

-c/--components と -e/--example は削除されたため、使用しないでください。-l/--llm は引き続きサポートされており、上記で使用しているフラグです。デフォルトでは管理対象テンプレートを使用し、意図的に空のプロジェクトを作成する場合は --empty、特定のテンプレートを使用する場合は --template <template> を指定します。フラグが拒否された場合は、レガシーコマンドを再試行するのではなく、イニシャライザーのヘルプを確認してください：npm create mastra@<tag> -- --help、npx create-mastra@<tag> --help、pnpm create mastra@<tag> --help、yarn dlx create-mastra@<tag> --help、または bunx create-mastra@<tag> --help。

インストールが完了するまで待ちます。ネットワーク速度によっては、1～2 分かかる場合があります。

ステップ 2：プロジェクト構成を確認する

作成後、プロジェクトに以下があることを確認します。

• Mastra の依存関係を含む package.json
• Mastra インスタンスをエクスポートする src/mastra/index.ts
• .env ファイル（作成が必要な場合があります）

ステップ 2.5：ブラウザーテスト用のブラウザーエージェントを追加する

ブラウザー機能をテストするには、ブラウザー対応エージェントを追加します。

1. ブラウザーパッケージをインストールします：

<pm> add @mastra/stagehand
# or for deterministic browser automation:
<pm> add @mastra/agent-browser

2. src/mastra/agents/ に browser-agent.ts を作成します：

import { Agent } from '@mastra/core/agent';
import { Memory } from '@mastra/memory';
import { StagehandBrowser } from '@mastra/stagehand';

export const browserAgent = new Agent({
  id: 'browser-agent',
  name: 'Browser Agent',
  instructions: `You are a helpful assistant that can browse the web to find information.`,
  model: '<provider>/<model>', // e.g., 'openai/gpt-4o'
  memory: new Memory(),
  browser: new StagehandBrowser({
    headless: false,
  }),
});

3. index.ts を更新してブラウザーエージェントを登録します：

import { browserAgent } from './agents/browser-agent';

// In Mastra config:
agents: { weatherAgent, browserAgent },

ステップ 3：環境変数を設定する

選択した LLM プロバイダーに応じて、必要な API キーを確認します。

プロバイダー	必要な環境変数
openai	OPENAI_API_KEY
anthropic	ANTHROPIC_API_KEY
groq	GROQ_API_KEY
google	GOOGLE_GENERATIVE_AI_API_KEY
cerebras	CEREBRAS_API_KEY
mistral	MISTRAL_API_KEY

次の順番で確認します：

1. まずグローバル環境を確認する：echo $<ENV_VAR_NAME> を実行し、キーがすでにグローバルに設定されているか確認します

   • グローバルに設定されていれば、プロジェクトに引き継がれるため、.env ファイルは不要です
   • ステップ 4 に進みます

2. プロジェクトの .env ファイルを確認する：グローバルに設定されていない場合は、プロジェクト内に .env ファイルが存在し、キーが含まれているか確認します

3. 必要な場合にのみユーザーに尋ねる：グローバル環境にも .env にもキーがない場合：

   • ユーザーに API キーを尋ねます
   • 提供されたキーを含む .env ファイルを作成します

選択したプロバイダーに対応するキーを 1 つだけ確認してください。すべてのプロバイダーのキーを確認しないでください。

ステップ 4：開発サーバーを起動する

プロジェクトディレクトリに移動し、開発サーバーを起動します：

cd <directory>/<project-name>
<packageManager> run dev

サーバーは通常、http://localhost:4111 で起動します。次に進む前に、サーバーの準備が完了するまで待ちます。

ステップ 5：Studio のスモークテストを行う

Chrome のブラウザー自動化ツールを使用して、Mastra Studio をテストします。

5.1 初期設定

1. tabs_context_mcp を使用してブラウザーコンテキストを取得します
2. tabs_create_mcp を使用して新しいタブを作成します
3. http://localhost:4111 に移動します

5.2 テストチェックリスト

Chrome 自動化ツールを使用して、以下のスモークテストを実行します。

ナビゲーションと基本的な読み込み

• Studio が正常に読み込まれることを確認します（ページに「Mastra Studio」が含まれているか、エージェント一覧が表示される）
• ホームページのスクリーンショットを撮影します

エージェントページ（/agents）

• エージェントページに移動します
• 少なくとも 1 つのエージェント（--default のサンプルエージェント）が一覧に表示されることを確認します
• スクリーンショットを撮影します

エージェント詳細（/agents/<agentId>/chat）

• エージェントをクリックして詳細を表示します
• エージェントの概要パネルが読み込まれることを確認します
• モデル設定パネルが表示されることを確認します
• スクリーンショットを撮影します

エージェントとのチャット

• エージェントにテストメッセージを送信します（例：「東京の天気はどうですか？」）
• 応答を待ちます
• 応答がチャットに表示されることを確認します
• 会話のスクリーンショットを撮影します

ブラウザーエージェント（/agents/browser-agent/chat）— ブラウザーエージェントを追加した場合

• browser-agent に移動します
• メッセージを送信します：「example.com にアクセスして、何が見えるか教えてください」
• エージェントがブラウザーを起動してコンテンツを抽出することを確認します
• 応答にページのコンテンツが含まれていることを確認します
• スクリーンショットを撮影します

ツールページ（/tools）

• ツールページに移動します
• ツール一覧が読み込まれることを確認します（get-weather ツールが表示されるはずです）
• スクリーンショットを撮影します

ツールの実行（/tools/get-weather）

• get-weather ツールをクリックして詳細ページを開きます
• 都市の入力フィールドを見つけ、テスト用の都市（例：「東京」）を入力します
• Submit ボタンをクリックします
• 実行が完了するまで待ちます
• 天気データ（気温、状況など）を含む JSON 出力が表示されることを確認します
• スクリーンショットを撮影します

ワークフローページ（/workflows）

• ワークフローページに移動します
• ワークフロー一覧が読み込まれることを確認します（weather-workflow が表示されるはずです）
• スクリーンショットを撮影します

ワークフローの実行（/workflows/weather-workflow）

• weather-workflow をクリックして詳細ページを開きます
• ビジュアルグラフが表示されることを確認します（ワークフローのステップが表示されます）
• 都市の入力フィールドを見つけ、テスト用の都市（例：「ロンドン」）を入力します
• Run ボタンをクリックします
• 実行が完了するまで待ちます
• ステップが成功を示していることを確認します（緑色のチェックマーク）
• クリックして JSON 出力のモーダルを表示します
• 実行の詳細と所要時間が表示されることを確認します
• スクリーンショットを撮影します

設定ページ（/settings）

• 設定ページに移動します
• 設定ページが読み込まれることを確認します
• スクリーンショットを撮影します

オブザーバビリティページ（/observability）

• オブザーバビリティページに移動します
• トレース一覧に最近のアクティビティ（前のテストによるもの）が表示されることを確認します
• トレースをクリックして詳細を表示します
• タイムラインビューにステップと所要時間が表示されることを確認します
• スクリーンショットを撮影します

スコアラーズページ（/evaluation?tab=scorers）

• /evaluation?tab=scorers に移動します（/scorers ではありません。そのルートは存在しません）
• スコアラー一覧が読み込まれることを確認します（サンプルスコアラーが 3 つ表示されます）
• スクリーンショットを撮影します

その他のページ（読み込みのみ確認）

• テンプレートページ（/templates）— スターターテンプレートのギャラリー
• Request Context ページ（/request-context）— JSON エディター
• プロセッサーページ（/processors）— 空の状態でも問題ありません
• MCP サーバーページ（/mcps）— 空の状態でも問題ありません

5.3 結果の報告

すべてのテストを完了したら、次の内容を要約します。

• 合格／失敗したテストの合計数
• 発生したエラー
• 撮影したスクリーンショット
• 見つかった問題への推奨事項

クイックリファレンス

ステップ	操作
プロジェクトの作成	<directory> 内で、ステップ 1 のパッケージマネージャー固有のコマンドを使用します
依存関係のインストール	作成時に自動で行われます
環境変数の設定	まずグローバル環境変数を確認し、次に .env を確認します。必要な場合のみユーザーに尋ねます
サーバーの起動	cd <directory>/<name> && <pm> run dev
Studio の URL	http://localhost:4111

トラブルシューティング

サーバーが起動しない

• .env に必要な API キーが設定されていることを確認します
• ポート 4111 が使用可能か確認します
• <pm> install を実行して依存関係を再インストールしてみます

ブラウザーが接続できない

• サーバーが完全に起動するまで数秒待ちます
• サーバーの準備完了メッセージがターミナルに表示されているか確認します
• ローカルホストをブロックするファイアウォールがないことを確認します

エージェントとのチャットが失敗する

• API キーが有効であることを確認します
• サーバーのログにエラーがないか確認します
• LLM プロバイダーの API にアクセスできることを確認します

ブラウザーエージェントが失敗する

• Google Chrome などのローカルの Chromium ブラウザーがインストールされ、アクセス可能であることを確認します
• ほかのブラウザーインスタンスが妨げになっていないことを確認します

Studio のルート

機能	ルート
エージェント	/agents
ワークフロー	/workflows
ツール	/tools
評価	/evaluation
スコアラー	/evaluation?tab=scorers
可観測性	/observability/traces
ログ	/observability/logs
MCP サーバー	/mcps
プロセッサー	/processors
テンプレート	/templates
リクエストコンテキスト	/request-context
設定	/settings

注意事項

• 管理対象のデフォルトテンプレートでは、エージェント、ツール、ストレージが生成されるため、スモークテストに適しています。別の開始地点が必要な場合に限り、--empty または --template <template> を使用します
• ユーザーが LLM プロバイダーを指定しない場合は、最も一般的な OpenAI をデフォルトとして使用します
• ドキュメント作成やデバッグのため、各主要ステップでスクリーンショットを撮影します
• テスト中は開発サーバーをバックグラウンドで実行したままにします
• 作成が対話形式にならないよう、明示的なフラグ（--llm、--no-git、--timeout）を渡します。以前のフラグを想定するのではなく、ステップ 1 に記載されているパッケージマネージャー固有の初期化ヘルプコマンドを使用します
• ブラウザーエージェントのテストでは、新しいブラウザー自動化機能を検証します
• エージェントまたはワークフローを実行すると、可観測性のトレースが自動的に表示されます