2026年、Vercelのプレビューデプロイを自動でテストする方法

簡潔な回答

ワークフローファイルを追加する必要はなく、ビルドログからプレビューURLをスクレイピングするスクリプトを書く必要もありません。TestSpriteはGitHub Appとしてインストールされ、パイプラインがすでに生成しているデプロイイベントをリッスンし、一度定義したパターンからプレビューURLを導き出し、そのURLに対してテストを実行し、結果をプルリクエストへのコメントとして投稿します。

セットアップにかかる時間は約10分で、GitHub Appをインストールするための管理者権限が必要ですが、リポジトリへの変更は一切必要ありません。

前提条件：プルリクエストがデプロイを生成することを確認する

TestSpriteはデプロイイベントをトリガーとして動作するため、他のすべてが機能する前にそのイベントが存在している必要があります。既存のプルリクエストを開き、クリック可能なURL付きでデプロイが表示されていることを確認し、そのURLを開いてプレビュー環境が実際に読み込まれるかを確認してください。

Vercelの場合、これはプロジェクトを一覧表示するボットコメント、Readyステータス、そしてプレビューへのリンクとしてプルリクエストに表示されます。AWS Amplify、Netlify、そしてGitHubデプロイを作成するセルフホスト型パイプラインも、それぞれの形式で同じシグナルを生成します — 重要なのは、デプロイが存在し、そのURLに到達可能であることです。

ステップ1 — GitHubをワークスペースに接続する

これはワークスペースごとに一度だけ行うセットアップです。TestSpriteでWorkspace Settings → Integrationsに移動し、GitHubの行を見つけてConnectをクリックします。リポジトリを所有する組織または個人アカウントを選択するためGitHubへリダイレクトされ、次にAll repositoriesまたはOnly select repositoriesを選んでInstall & Authorizeをクリックします。

承認する前に、要求される権限について知っておく価値があります。

書き込みアクセスは、テスト結果をプルリクエストやコミットに書き戻すために使用されます。TestSpriteはコミットをプッシュしたり、ワークフローファイルを変更したりすることはありません。インストール中に組織が一覧に表示されない場合、その組織にGitHub Appsをインストールする権限がないということです — 組織オーナーによる承認が必要です。

ステップ2 — リポジトリをプロジェクトに接続する

接続したいTestSpriteプロジェクトを開き、GitHub Actionタブに移動してConnect GitHub Actionをクリックします。次に、テストをどのようにトリガーするかを選択します。

開始するにはトリガーが一つあれば十分です。両方作成することもでき、それぞれ独立して実行されます。

ステップ3 — 「デプロイ完了」を意味するイベントを選ぶ

Pull Requestタブを選択し、動作するプレビューデプロイを持つ既存のプルリクエストのURLを貼り付けて、Detect Eventsをクリックします。TestSpriteはそのプルリクエストで見つかったCI/CDイベント — GitHub Actionsのチェック、VercelやAmplifyからのボットコメント、ワークフロー実行 — を一覧表示し、どれが実行を開始するトリガーになるかを選択します。

デプロイが稼働し、URLに到達可能になった後に発火するイベントを選んでください。これはセットアップを誤る最も一般的な原因です — ビルド開始時に発火するイベントを選んでしまうと、まだ立ち上がっていないURLに対してテストが実行され、すべてのテストが失敗します。

ステップ4 — ターゲットURLパターンを入力する

ホスティングプロバイダーごとにプレビューURLの命名方法は異なるため、任意のプルリクエストに対してURLをどう構築するかをTestSpriteに指定します。5つのプレースホルダーが利用できます。

実際のプレビューURLと1文字ずつ照らし合わせてパターンを確認してください。

Vercelのデフォルトのプレビューホスト名はブランチから構築されるため、通常は{pr}ではなく{branch-slug}が適切なプレースホルダーになります。ホスティング先が予測不能なランダムなサブドメインを生成する場合は、プレビュー環境用の安定したエイリアスURLを設定し、代わりにそれを使用してください。

プッシュトリガーにはパターンはまったく必要ありません — 選択したTestSprite環境に設定されたURLに対して実行されるため、devにはDevを、mainにはProductionを選んでください。

ステップ5 — 保存する前にテストイベントを送信する

Send Test Eventをクリックします。これは実際のトリガーとまったく同じように、サンプルのプルリクエストに対してテストを実行するため、本番運用に入る前にフロー全体をプレビューできます。約30秒待ってからGitHub上のプルリクエストに戻ると、TestSpriteのコメントが表示されます。

先に進む前に、そのコメント内のURLを開いてください。到達可能であること、想定した環境を指していることを確認します。もし間違っていれば、次のプルリクエストで判明するのを待つのではなく、パターンを修正してもう一度テストイベントを送信してください。実行が完了すると、TestSpriteは同じコメントを結果で更新します。

テストイベントが正しく見えたら、Create Triggerをクリックします。トリガー一覧にActiveとして表示され、以降のすべてのプルリクエストで自動的に実行されます。意図的に設定しておく価値のあるオプションのトグルが2つあります。

プレビューがDeployment Protectionの背後にある場合

これは一見うまく機能しているように見える失敗パターンです。VercelのDeployment Protectionが有効な場合、すべてのプレビューURLは認証の壁の背後にあり、外部のテスターはアプリケーションの代わりにログインページを受け取ります。テストはエラーにはなりません — 誰も想定していなかったページを記述するだけです。

ステップ5でのチェックがこれを検出します — TestSpriteのコメントにあるURLをプライベートウィンドウで開いてみてください。Vercelのログイン画面が表示されれば、保護が有効になっています。対処法は2通りあります。プレビュー環境の保護を無効にするか、VercelのProtection Bypass for Automationを使用することです。これはシークレットを生成し、Vercelはそれをヘッダーだけでなくx-vercel-protection-bypassクエリパラメータとしても受け付けます。ターゲットURLパターンは単なるURLなので、クエリパラメータ形式を追記できます。

https://app-git-{branch-slug}-team.vercel.app?x-vercel-protection-bypass=YOUR_SECRET

シークレットはProject Settings → Deployment Protection → Protection Bypass for Automationの下で生成します。この設定は慎重に扱ってください — バイパスシークレットが設定フィールドに保存されるため、プレビューに機密情報が含まれていない場合は、プレビュー環境の保護を無効にする方がすっきりした選択肢です。

結果の読み方

実行が完了すると、TestSpriteはプルリクエストのコメント（またはコミットのチェック）を結果で更新します。コメントは構造化されており、AIエージェントがコードを書いた場合に最も重要になるのは最後の行です。

すべての結果はTestSprite内の完全なレポートにリンクしています。

セットアップを確認する

この連携に頼る前に、以下の5点をすべて確認してください。

1. ワークスペースでGitHub連携がConnectedと表示されている

2. プロジェクトのGitHub Actionタブにリポジトリが表示されている

3. トリガーが一覧に表示され、有効になっている

4. テストイベントによってTestSpriteのコメント（プルリクエスト）またはチェック（プッシュ）が生成された

5. そのコメントまたはチェック内のURLが、正しいデプロイ環境を開く

トラブルシューティング

コマンドラインでの代替方法

パイプラインがすでにデプロイを生成している場合、GitHub Appが正しい選択です。もし自分のワークフローから実行を駆動したい場合、あるいはそもそもGitHubを使っていない場合は、オープンソースのTestSprite CLIが任意のCIシステムから同じ仕事をこなします。インストールは無料で、Apache-2.0ライセンスです。

npm install -g @testsprite/testsprite-cli
testsprite setup

すでに解決済みのURLをプロジェクトに指定し、スイートを実行して結果を得ます。

testsprite project update prj_abc123 --url "$PREVIEW_URL"
testsprite test run --all --project prj_abc123 --wait --output json
#   exit 0 = everything passed, exit 1 = something is broken

testsprite ci init githubはこの経路用のワークフローをスキャフォールドします。CLIが必要とするのは環境変数のTESTSPRITE_API_KEYだけなので、CircleCI、GitLab、Jenkins、Azure Pipelinesにも同様に簡単に組み込めます。これらのシステムがネイティブに取り込めるサイドカーには--report junit --report-file <path>を使用してください。

重視しているフローがアプリケーション自体のログインの背後にある場合は、プロジェクトにテストアカウントを保存しておくことで実行時に認証できます。両方のフラグはセットで必要です。

testsprite project update prj_abc123 \
  --username qa@example.com \
  --password-file ./.secrets/qa-password

よくある質問