API テスト

はじめに

Playwright は、アプリケーションの REST API にアクセスするために使用できます。

ページをロードしたり、その中のJSコードを実行したりせずに、Node.jsから直接サーバーにリクエストを送信したい場合があります。役立ついくつかの例を挙げます。

サーバー API をテストする。
テストで Web アプリケーションにアクセスする前に、サーバー側の状態を準備する。
ブラウザーでいくつかのアクションを実行した後、サーバー側の事後条件を検証する。

これらすべては、APIRequestContext メソッドで実現できます。

API テストの記述

APIRequestContext は、あらゆる種類の HTTP(S) リクエストをネットワーク経由で送信できます。

次の例は、Playwright を使用して GitHub API を介した問題作成をテストする方法を示しています。テストスイートは以下を実行します。

テストを実行する前に新しいリポジトリを作成する。
いくつかの問題を作成し、サーバーの状態を検証する。
テストを実行した後、リポジトリを削除する。

設定

GitHub API は認証を必要とするため、すべてのテストに対して一度だけトークンを設定します。その際に、テストを簡素化するために baseURL も設定します。これらは設定ファイルに入れるか、test.use() を使用してテストファイルに入れることができます。

playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
  use: {
    // All requests we send go to this API endpoint.
    baseURL: 'https://api.github.com',
    extraHTTPHeaders: {
      // We set this header per GitHub guidelines.
      'Accept': 'application/vnd.github.v3+json',
      // Add authorization token to all requests.
      // Assuming personal access token available in the environment.
      'Authorization': `token ${process.env.API_TOKEN}`,
    },
  }
});

プロキシ設定

テストをプロキシの背後で実行する必要がある場合は、これを設定で指定でき、request フィクスチャが自動的にそれを認識します。

playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
  use: {
    proxy: {
      server: 'http://my-proxy:8080',
      username: 'user',
      password: 'secret'
    },
  }
});

テストの記述

Playwright Test には、baseURL や extraHTTPHeaders などの指定した設定オプションを尊重し、すぐにリクエストを送信できる組み込みの request フィクスチャが付属しています。

次に、リポジトリに新しい課題を作成するいくつかのテストを追加できます。

const REPO = 'test-repo-1';
const USER = 'github-username';

test('should create a bug report', async ({ request }) => {
  const newIssue = await request.post(`/repos/${USER}/${REPO}/issues`, {
    data: {
      title: '[Bug] report 1',
      body: 'Bug description',
    }
  });
  expect(newIssue.ok()).toBeTruthy();

  const issues = await request.get(`/repos/${USER}/${REPO}/issues`);
  expect(issues.ok()).toBeTruthy();
  expect(await issues.json()).toContainEqual(expect.objectContaining({
    title: '[Bug] report 1',
    body: 'Bug description'
  }));
});

test('should create a feature request', async ({ request }) => {
  const newIssue = await request.post(`/repos/${USER}/${REPO}/issues`, {
    data: {
      title: '[Feature] request 1',
      body: 'Feature description',
    }
  });
  expect(newIssue.ok()).toBeTruthy();

  const issues = await request.get(`/repos/${USER}/${REPO}/issues`);
  expect(issues.ok()).toBeTruthy();
  expect(await issues.json()).toContainEqual(expect.objectContaining({
    title: '[Feature] request 1',
    body: 'Feature description'
  }));
});

セットアップとティアダウン

これらのテストは、リポジトリが存在することを前提としています。おそらく、テストを実行する前に新しいリポジトリを作成し、実行後に削除したいと思うでしょう。そのためには beforeAll と afterAll フックを使用します。

test.beforeAll(async ({ request }) => {
  // Create a new repository
  const response = await request.post('/user/repos', {
    data: {
      name: REPO
    }
  });
  expect(response.ok()).toBeTruthy();
});

test.afterAll(async ({ request }) => {
  // Delete the repository
  const response = await request.delete(`/repos/${USER}/${REPO}`);
  expect(response.ok()).toBeTruthy();
});

リクエストコンテキストの使用

舞台裏では、request フィクスチャは実際には apiRequest.newContext() を呼び出します。より詳細な制御が必要な場合は、いつでも手動で行うことができます。以下は、上記の beforeAll と afterAll と同じことを行うスタンドアロンのスクリプトです。

import { request } from '@playwright/test';
const REPO = 'test-repo-1';
const USER = 'github-username';

(async () => {
  // Create a context that will issue http requests.
  const context = await request.newContext({
    baseURL: 'https://api.github.com',
  });

  // Create a repository.
  await context.post('/user/repos', {
    headers: {
      'Accept': 'application/vnd.github.v3+json',
      // Add GitHub personal access token.
      'Authorization': `token ${process.env.API_TOKEN}`,
    },
    data: {
      name: REPO
    }
  });

  // Delete a repository.
  await context.delete(`/repos/${USER}/${REPO}`, {
    headers: {
      'Accept': 'application/vnd.github.v3+json',
      // Add GitHub personal access token.
      'Authorization': `token ${process.env.API_TOKEN}`,
    }
  });
})();

UIテストからのAPIリクエスト送信

ブラウザ内でテストを実行する際、アプリケーションのHTTP APIを呼び出したい場合があります。これは、テストを実行する前にサーバーの状態を準備する必要がある場合や、ブラウザでいくつかの操作を実行した後にサーバー上のいくつかの事後条件を確認する必要がある場合に役立ちます。これらすべては、APIRequestContext メソッドで実現できます。

事前条件の設定

次のテストは、API経由で新しい課題を作成し、プロジェクトのすべての課題リストに移動して、それがリストの先頭に表示されることを確認します。

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

const REPO = 'test-repo-1';
const USER = 'github-username';

// Request context is reused by all tests in the file.
let apiContext;

test.beforeAll(async ({ playwright }) => {
  apiContext = await playwright.request.newContext({
    // All requests we send go to this API endpoint.
    baseURL: 'https://api.github.com',
    extraHTTPHeaders: {
      // We set this header per GitHub guidelines.
      'Accept': 'application/vnd.github.v3+json',
      // Add authorization token to all requests.
      // Assuming personal access token available in the environment.
      'Authorization': `token ${process.env.API_TOKEN}`,
    },
  });
});

test.afterAll(async ({ }) => {
  // Dispose all responses.
  await apiContext.dispose();
});

test('last created issue should be first in the list', async ({ page }) => {
  const newIssue = await apiContext.post(`/repos/${USER}/${REPO}/issues`, {
    data: {
      title: '[Feature] request 1',
    }
  });
  expect(newIssue.ok()).toBeTruthy();

  await page.goto(`https://github.com/${USER}/${REPO}/issues`);
  const firstIssue = page.locator(`a[data-hovercard-type='issue']`).first();
  await expect(firstIssue).toHaveText('[Feature] request 1');
});

事後条件の検証

次のテストは、ブラウザのユーザーインターフェース経由で新しい課題を作成し、API経由で作成されたかどうかをチェックします。

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

const REPO = 'test-repo-1';
const USER = 'github-username';

// Request context is reused by all tests in the file.
let apiContext;

test.beforeAll(async ({ playwright }) => {
  apiContext = await playwright.request.newContext({
    // All requests we send go to this API endpoint.
    baseURL: 'https://api.github.com',
    extraHTTPHeaders: {
      // We set this header per GitHub guidelines.
      'Accept': 'application/vnd.github.v3+json',
      // Add authorization token to all requests.
      // Assuming personal access token available in the environment.
      'Authorization': `token ${process.env.API_TOKEN}`,
    },
  });
});

test.afterAll(async ({ }) => {
  // Dispose all responses.
  await apiContext.dispose();
});

test('last created issue should be on the server', async ({ page }) => {
  await page.goto(`https://github.com/${USER}/${REPO}/issues`);
  await page.getByText('New Issue').click();
  await page.getByRole('textbox', { name: 'Title' }).fill('Bug report 1');
  await page.getByRole('textbox', { name: 'Comment body' }).fill('Bug description');
  await page.getByText('Submit new issue').click();
  const issueId = new URL(page.url()).pathname.split('/').pop();

  const newIssue = await apiContext.get(
      `https://api.github.com/repos/${USER}/${REPO}/issues/${issueId}`
  );
  expect(newIssue.ok()).toBeTruthy();
  expect(newIssue.json()).toEqual(expect.objectContaining({
    title: 'Bug report 1'
  }));
});

認証状態の再利用

Webアプリはクッキーベースまたはトークンベースの認証を使用し、認証状態はクッキーとして保存されます。Playwrightは、認証済みコンテキストからストレージ状態を取得し、その状態を持つ新しいコンテキストを作成するために使用できるapiRequestContext.storageState()メソッドを提供します。

ストレージ状態は、BrowserContext と APIRequestContext の間で交換可能です。これを使用して、API呼び出し経由でログインし、既にクッキーがある新しいコンテキストを作成できます。次のコードスニペットは、認証済みの APIRequestContext から状態を取得し、その状態を持つ新しい BrowserContext を作成します。

const requestContext = await request.newContext({
  httpCredentials: {
    username: 'user',
    password: 'passwd'
  }
});
await requestContext.get(`https://api.example.com/login`);
// Save storage state into the file.
await requestContext.storageState({ path: 'state.json' });

// Create a new context with the saved storage state.
const context = await browser.newContext({ storageState: 'state.json' });

コンテキストリクエストとグローバルリクエストの比較

APIRequestContext には2つのタイプがあります。

BrowserContext に関連付けられたもの
apiRequest.newContext() 経由で作成された分離されたインスタンス

主な違いは、browserContext.request と page.request 経由でアクセスできる APIRequestContext は、ブラウザコンテキストからリクエストの Cookie ヘッダーを埋め込み、APIResponse に Set-Cookie ヘッダーがある場合、ブラウザのクッキーを自動的に更新することです。

test('context request will share cookie storage with its browser context', async ({
  page,
  context,
}) => {
  await context.route('https://www.github.com/', async route => {
    // Send an API request that shares cookie storage with the browser context.
    const response = await context.request.fetch(route.request());
    const responseHeaders = response.headers();

    // The response will have 'Set-Cookie' header.
    const responseCookies = new Map(responseHeaders['set-cookie']
        .split('\n')
        .map(c => c.split(';', 2)[0].split('=')));
    // The response will have 3 cookies in 'Set-Cookie' header.
    expect(responseCookies.size).toBe(3);
    const contextCookies = await context.cookies();
    // The browser context will already contain all the cookies from the API response.
    expect(new Map(contextCookies.map(({ name, value }) =>
      [name, value])
    )).toEqual(responseCookies);

    await route.fulfill({
      response,
      headers: { ...responseHeaders, foo: 'bar' },
    });
  });
  await page.goto('https://www.github.com/');
});

APIRequestContext にブラウザコンテキストからクッキーを使用および更新させたくない場合は、独自の分離されたクッキーを持つ APIRequestContext の新しいインスタンスを手動で作成できます。

test('global context request has isolated cookie storage', async ({
  page,
  context,
  browser,
  playwright
}) => {
  // Create a new instance of APIRequestContext with isolated cookie storage.
  const request = await playwright.request.newContext();
  await context.route('https://www.github.com/', async route => {
    const response = await request.fetch(route.request());
    const responseHeaders = response.headers();

    const responseCookies = new Map(responseHeaders['set-cookie']
        .split('\n')
        .map(c => c.split(';', 2)[0].split('=')));
    // The response will have 3 cookies in 'Set-Cookie' header.
    expect(responseCookies.size).toBe(3);
    const contextCookies = await context.cookies();
    // The browser context will not have any cookies from the isolated API request.
    expect(contextCookies.length).toBe(0);

    // Manually export cookie storage.
    const storageState = await request.storageState();
    // Create a new context and initialize it with the cookies from the global request.
    const browserContext2 = await browser.newContext({ storageState });
    const contextCookies2 = await browserContext2.cookies();
    // The new browser context will already contain all the cookies from the API response.
    expect(
        new Map(contextCookies2.map(({ name, value }) => [name, value]))
    ).toEqual(responseCookies);

    await route.fulfill({
      response,
      headers: { ...responseHeaders, foo: 'bar' },
    });
  });
  await page.goto('https://www.github.com/');
  await request.dispose();
});

はじめに​

API テストの記述​

設定​

テストの記述​

セットアップとティアダウン​

リクエストコンテキストの使用​

UIテストからのAPIリクエスト送信​

事前条件の設定​

事後条件の検証​

認証状態の再利用​

コンテキストリクエストとグローバルリクエストの比較​