グローバルセットアップとティアダウン

はじめに

グローバルセットアップとティアダウンを設定する方法は2つあります: グローバルセットアップファイルを使用し、設定ファイルのglobalSetupの下で設定する方法、またはプロジェクト依存関係を使用する方法です。プロジェクト依存関係を使用すると、他のすべてのプロジェクトが実行される前に実行されるプロジェクトを定義します。これはPlaywrightテストランナーとの統合がより優れているため、推奨されるアプローチです。HTMLレポートにグローバルセットアップが含まれ、トレースが記録され、フィクスチャを使用できます。2つのアプローチの詳細な比較については、以下の表を参照してください。

機能	プロジェクト依存関係 (推奨)	globalSetup (設定オプション)
全てのテストの前に実行	✅ はい	✅ はい
HTMLレポートの可視性	✅ 個別のプロジェクトとして表示	❌ 表示されません
トレース記録	✅ 完全なトレースが利用可能	❌ サポートされていません
Playwrightフィクスチャ	✅ 完全にサポートされています	❌ サポートされていません
ブラウザ管理	✅ browserフィクスチャ経由	❌ browserType.launch()による完全な手動管理
並列実行とリトライ	✅ 標準設定でサポート	❌ 該当なし
headlessやtestIdAttributeのような設定オプション	✅ 自動的に適用	❌ 無視されます

オプション1: プロジェクト依存関係

プロジェクト依存関係とは、他のプロジェクトのテストが実行される前に実行する必要があるプロジェクトのリストです。これらは、あるプロジェクトが最初に実行されることに依存するようにグローバルセットアップアクションを設定するのに役立ちます。依存関係を使用すると、グローバルセットアップでトレースやその他のアーティファクトを生成できます。

セットアップ

まず、「setup db」という名前の新しいプロジェクトを追加します。次に、global.setup.tsという名前のファイルと一致させるために、testProject.testMatchプロパティを設定します。

playwright.config.ts

import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  // ...
  projects: [
    {
      name: 'setup db',
      testMatch: /global\.setup\.ts/,
    },
    // {
    //   other project
    // }
  ]
});

次に、セットアッププロジェクトに依存するプロジェクトにtestProject.dependenciesプロパティを追加し、前のステップで定義した依存プロジェクトの名前を配列に渡します

playwright.config.ts

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  // ...
  projects: [
    {
      name: 'setup db',
      testMatch: /global\.setup\.ts/,
    },
    {
      name: 'chromium with db',
      use: { ...devices['Desktop Chrome'] },
      dependencies: ['setup db'],
    },
  ]
});

この例では、「chromium with db」プロジェクトは「setup db」プロジェクトに依存しています。次に、プロジェクトのルートレベルに保存されるセットアップテストを作成します（セットアップおよびティアダウンコードは、test()関数を呼び出すことで通常のテストとして定義する必要があることに注意してください）

tests/global.setup.ts

import { test as setup } from '@playwright/test';

setup('create new database', async ({ }) => {
  console.log('creating new database...');
  // Initialize the database
});

tests/menu.spec.ts

import { test, expect } from '@playwright/test';

test('menu', async ({ page }) => {
  // Your test that depends on the database
});

ティアダウン

セットアッププロジェクトにtestProject.teardownプロパティを追加することで、セットアップをティアダウンできます。これは、すべての依存プロジェクトが実行された後に実行されます。

まず、「cleanup db」という名前のtestProject.teardownプロパティをセットアッププロジェクトに追加します。これは前のステップでティアダウンプロジェクトに付けた名前です。

playwright.config.ts

import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  // ...
  projects: [
    {
      name: 'setup db',
      testMatch: /global\.setup\.ts/,
      teardown: 'cleanup db',
    },
    {
      name: 'cleanup db',
      testMatch: /global\.teardown\.ts/,
    },
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
      dependencies: ['setup db'],
    },
  ]
});

次に、プロジェクトの`tests`ディレクトリに`global.teardown.ts`ファイルを作成します。これは、すべてのテストが実行された後、データベースからデータを削除するために使用されます。

tests/global.teardown.ts

import { test as teardown } from '@playwright/test';

teardown('delete database', async ({ }) => {
  console.log('deleting test database...');
  // Delete the database
});

テストのフィルタリング

--grep/--grep-invert、--shard、コマンドラインで場所を指定して直接フィルタリングする、またはtest.only()を使用するなどのすべてのテストフィルタリングオプションは、実行する主要なテストを直接選択します。それらのテストが依存関係を持つプロジェクトに属している場合、これらの依存関係のすべてのテストも実行されます。

すべての依存関係とティアダウンを無視するには、`--no-deps`コマンドラインオプションを渡すことができます。直接選択したプロジェクトのみが実行されます。

その他の例

詳細な例については、以下をご覧ください

• 私たちの認証ガイド
• 私たちのブログ投稿 プロジェクト依存関係を使用してログインを再利用するPlaywrightのより良いグローバルセットアップ
• v1.31リリースビデオでデモを見る

オプション2: globalSetupとglobalTeardownの設定

設定ファイルの`globalSetup`オプションを使用して、すべてのテストを実行する前に一度何かをセットアップすることができます。グローバルセットアップファイルは、設定オブジェクトを受け取る単一の関数をエクスポートする必要があります。この関数は、すべてのテストの前に一度実行されます。

同様に、`globalTeardown`を使用して、すべてのテストの後に一度何かを実行します。または、`globalSetup`がグローバルティアダウンとして使用される関数を返すようにすることもできます。ポート番号、認証トークンなどのデータを、環境変数を使用してグローバルセットアップからテストに渡すことができます。

注意

globalSetupとglobalTeardownにはいくつかの機能が不足していることに注意してください — 詳細な比較についてははじめにセクションを参照してください。完全な機能サポートを得るには、代わりにプロジェクト依存関係の使用を検討してください。

playwright.config.ts

import { defineConfig } from '@playwright/test';

export default defineConfig({
  globalSetup: require.resolve('./global-setup'),
  globalTeardown: require.resolve('./global-teardown'),
});

例

認証を一度行い、認証状態をテストで再利用するグローバルセットアップの例です。これは設定ファイルから`baseURL`と`storageState`オプションを使用します。

global-setup.ts

import { chromium, type FullConfig } from '@playwright/test';

async function globalSetup(config: FullConfig) {
  const { baseURL, storageState } = config.projects[0].use;
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto(baseURL!);
  await page.getByLabel('User Name').fill('user');
  await page.getByLabel('Password').fill('password');
  await page.getByText('Sign in').click();
  await page.context().storageState({ path: storageState as string });
  await browser.close();
}

export default globalSetup;

設定ファイルで`globalSetup`、`baseURL`、`storageState`を指定します。

playwright.config.ts

import { defineConfig } from '@playwright/test';
export default defineConfig({
  globalSetup: require.resolve('./global-setup'),
  use: {
    baseURL: 'https://:3000/',
    storageState: 'state.json',
  },
});

グローバルセットアップによって投入された`storageState`を指定するため、テストはすでに認証された状態で開始されます。

import { test } from '@playwright/test';

test('test', async ({ page }) => {
  await page.goto('/');
  // You are signed in!
});

`process.env`を介して環境変数として設定することで、グローバルセットアップファイルから任意のデータをテストで利用可能にすることができます。

global-setup.ts

import type { FullConfig } from '@playwright/test';

async function globalSetup(config: FullConfig) {
  process.env.FOO = 'some data';
  // Or a more complicated data structure as JSON:
  process.env.BAR = JSON.stringify({ some: 'data' });
}

export default globalSetup;

テストは、グローバルセットアップで設定された`process.env`プロパティにアクセスできます。

import { test } from '@playwright/test';

test('test', async ({ page }) => {
  // environment variables which are set in globalSetup are only available inside test().
  const { FOO, BAR } = process.env;

  // FOO and BAR properties are populated.
  expect(FOO).toEqual('some data');

  const complexData = JSON.parse(BAR);
  expect(BAR).toEqual({ some: 'data' });
});

グローバルセットアップ中の失敗のトレースのキャプチャ

場合によっては、グローバルセットアップ中に発生した失敗のトレースをキャプチャすると役立つ場合があります。これを行うには、セットアップでトレースを開始し、エラーがスローされる前にエラーが発生した場合はトレースを停止することを保証する必要があります。これは、セットアップを`try...catch`ブロックでラップすることで実現できます。ここに、グローバルセットアップの例を拡張してトレースをキャプチャする例を示します。

global-setup.ts

import { chromium, type FullConfig } from '@playwright/test';

async function globalSetup(config: FullConfig) {
  const { baseURL, storageState } = config.projects[0].use;
  const browser = await chromium.launch();
  const context = await browser.newContext();
  const page = await context.newPage();
  try {
    await context.tracing.start({ screenshots: true, snapshots: true });
    await page.goto(baseURL!);
    await page.getByLabel('User Name').fill('user');
    await page.getByLabel('Password').fill('password');
    await page.getByText('Sign in').click();
    await context.storageState({ path: storageState as string });
    await context.tracing.stop({
      path: './test-results/setup-trace.zip',
    });
    await browser.close();
  } catch (error) {
    await context.tracing.stop({
      path: './test-results/failed-setup-trace.zip',
    });
    await browser.close();
    throw error;
  }
}

export default globalSetup;