Playwrightのrequestで、APIを直接テストする方法

​​Playwright​APIテスト,E2Eテスト,TypeScript

Playwright のテストで受け取れる request(API を呼ぶためのフィクスチャ)を使うと、ブラウザを開かずに REST API へ直接 HTTP リクエストを送れます。画面のない API のテスト(作成・取得・削除の応答やステータスコードの確認)を、E2E テストと同じ npx playwright test で書けます。画面のテストの前に API でデータを用意する使い方もできます。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4、@playwright/test 1.63.0、TypeScript 5.9.3 です。テストの相手には、メモリにデータを持つだけの小さな Todo API を Node.js で書き、webServer で起動しました。画面を使うテストは Chromium(ヘッドレス)で動かしています。実在する外部の API、HTTPS、multipart でのファイル送信、CI のサービス上での実行は試していません。

設定ファイルに API の URL と認証ヘッダーを書く

request は、設定ファイルの use に書いた baseURL と extraHTTPHeaders を使います(公式ドキュメントの API テストの説明)。検証では、Todo を作るときに Authorization: Bearer test-token が必要な API を用意し、次の設定にしました。

ts
// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  reporter: 'list',
  workers: 1,
  use: {
    baseURL: 'http://localhost:3000',
    extraHTTPHeaders: {
      Authorization: 'Bearer test-token',
    },
  },
  webServer: {
    command: 'node server.mjs',
    url: 'http://localhost:3000/api/todos',
    stdout: 'pipe',
  },
});

baseURL があるので、テストの中では /api/todos のようにパスだけを書けます。extraHTTPHeaders のヘッダーは、すべてのリクエストに付きます。

作成・取得・削除をテストする

テストの関数で { request } を受け取り、request.post() や request.get() を呼びます。

ts
// tests/todos.spec.ts
import { test, expect } from '@playwright/test';

test('Todo を作ると 201 が返り、取得できる', async ({ request }) => {
  const created = await request.post('/api/todos', {
    data: { title: '牛乳を買う' },
  });
  expect(created.status()).toBe(201);
  expect(created.headers()['content-type']).toContain('application/json');
  const todo = await created.json();
  expect(todo).toMatchObject({ title: '牛乳を買う', done: false });

  const fetched = await request.get(`/api/todos/${todo.id}`);
  await expect(fetched).toBeOK();
  expect(await fetched.json()).toEqual(todo);
});

test('title がないと 422 が返る', async ({ request }) => {
  const res = await request.post('/api/todos', { data: {} });
  expect(res.status()).toBe(422);
  expect(await res.json()).toEqual({ error: 'title is required' });
});

test('削除すると 204 が返り、そのあとは 404 になる', async ({ request }) => {
  const todo = await (await request.post('/api/todos', { data: { title: '消すもの' } })).json();
  const deleted = await request.delete(`/api/todos/${todo.id}`);
  expect(deleted.status()).toBe(204);
  const after = await request.get(`/api/todos/${todo.id}`);
  expect(after.status()).toBe(404);
});

data にオブジェクトを渡すと JSON の文字列になり、content-type は application/json になります。返ってきた本文は json() でオブジェクトとして読めます。toBeOK() は、ステータスコードが 200〜299 であることを確かめるアサーションです(APIResponseAssertions の説明)。

実行した結果です。[WebServer] の行は、検証用のサーバーが受け取ったリクエストを表示したもので、auth=あり は Authorization ヘッダーが付いていたことを示します。

text
$ npx playwright test tests/todos.spec.ts
[WebServer] listening on port 3000
[WebServer] GET /api/todos content-type=- auth=なし

Running 3 tests using 1 worker

[WebServer] POST /api/todos content-type=application/json auth=あり
[WebServer] GET /api/todos/1 content-type=- auth=あり
  ✓  1 tests/todos.spec.ts:3:5 › Todo を作ると 201 が返り、取得できる (66ms)
[WebServer] POST /api/todos content-type=application/json auth=あり
  ✓  2 tests/todos.spec.ts:17:5 › title がないと 422 が返る (15ms)
[WebServer] POST /api/todos content-type=application/json auth=あり
[WebServer] DELETE /api/todos/2 content-type=- auth=あり
[WebServer] GET /api/todos/2 content-type=- auth=あり
  ✓  3 tests/todos.spec.ts:23:5 › 削除すると 204 が返り、そのあとは 404 になる (21ms)

  3 passed (1.0s)

最初の GET /api/todos(auth=なし)は、webServer が設定の url に送った、サーバーの起動を待つための問い合わせです(公式ドキュメントの webServer の説明)。テストから送ったリクエストには、すべてトークンが付いていました。3回続けて実行したところ、全体の時間は 1.0秒、826ミリ秒、973ミリ秒で、テスト1件は 12〜66ミリ秒でした。

request だけを使うテストは、ブラウザを起動しません。環境変数 PLAYWRIGHT_BROWSERS_PATH に存在しないフォルダを指定し、ブラウザが見つからない状態にしても、この3件は通りました。同じ状態で page を使うテストを動かすと、browserType.launch: Executable doesn't exist at … で失敗しました。

4xx が返っても、テストは自動では失敗しない

request.get() などは、404 や 500 が返っても例外を投げず、そのまま応答を返します(APIRequestContext の説明の failOnStatusCode)。上の 422 や 404 のテストが書けるのはこのためですが、成功を期待する場面では、ステータスコードを自分で確かめる必要があります。

確かめ方によって、失敗したときに出る情報が違います。存在しない /api/todos/999 を取得して、3つの書き方で失敗させました。

expect(res.status()).toBe(200) では、数字の違いしか分かりません。

text
    Error: expect(received).toBe(expected) // Object.is equality

    Expected: 200
    Received: 404
    …(以下略)

await expect(res).toBeOK() では、送ったリクエストのヘッダーと、返ってきた本文まで表示されました。

text
    Error: expect(response).toBeOK() failed


    Call log:
    → GET http://localhost:3000/api/todos/999
      user-agent: Playwright/1.63.0 (x64; ubuntu 24.04) node/22.23
      accept: */*
      accept-encoding: gzip,deflate,br
      Authorization: Bearer test-token
    ← 404 Not Found
      content-type: application/json; charset=utf-8
      …(中略)

    Response text:
    {"error":"not found"}
    …(以下略)

request.get('/api/todos/999', { failOnStatusCode: true }) のように failOnStatusCode を付けると、2xx と 3xx 以外ではその場で例外になり、Error: apiRequestContext.get: 404 Not Found に続いて、同じように本文とヘッダーが表示されました。API がエラーの理由を本文で返す場合は、toBeOK() か failOnStatusCode を使うと、失敗の原因をすぐに読めます。

注意

toBeOK() の失敗の表示には、Authorization などのリクエストヘッダーがそのまま出ます。CI のログやテストのレポートを外部に公開している場合は、本物のトークンもそこに出ることになります。

ログインの Cookie は、同じ request の中で引き継がれる

フォームで送る API には、data ではなく form を使います。content-type は application/x-www-form-urlencoded になります。

ts
test('form で送ると urlencoded になり、Cookie は同じ context に残る', async ({ request }) => {
  const login = await request.post('/login', {
    form: { user: 'alice', password: 'secret' },
  });
  await expect(login).toBeOK();

  const me = await request.get('/api/me');
  await expect(me).toBeOK();
  expect(await me.json()).toEqual({ user: 'alice' });
});

記事のコードでは、Cookie の中身を表示する console.log の行を省いています。ログインの応答の Set-Cookie(sid=…; Path=/; HttpOnly)は request に保存され、続く /api/me に送られてテストが通りました。request.storageState() で中身を見ると、sid が httpOnly=true で入っていました。一方、別のテストで受け取った request から /api/me を呼ぶと 401 でした。組み込みのフィクスチャの一覧にあるとおり、request はテストごとに別の context なので、ログインの状態はテストをまたいで残りません。

data に文字列を渡したときは注意が必要です。data: 'title=牛乳' で送ると、content-type は application/octet-stream になり、JSON を期待する検証用の API は 400 を返しました。オブジェクトなら JSON、文字列ならそのままのバイト列として送られる、というのが APIRequestContext の説明の data の仕様です。

request.newContext() も設定の use を引き継いでいた

トークンを付けずに送ると 401 が返ることも確かめるため、@playwright/test の request.newContext() で新しい context を作り、baseURL だけを渡すテストを書きました。

ts
import { test, expect, request as playwrightRequest } from '@playwright/test';

// このテストは失敗した(401 ではなく 201 が返った)
test('トークンなしの context では 401 になる', async () => {
  const anonymous = await playwrightRequest.newContext({
    baseURL: 'http://localhost:3000',
  });
  const res = await anonymous.post('/api/todos', { data: { title: 'x' } });
  expect(res.status()).toBe(401);
  await anonymous.dispose();
});

結果は Expected: 401 / Received: 201 で失敗しました。サーバーの記録は auth=あり で、設定ファイルの Authorization が付いていました。newContext() に何も渡さずに作っても、baseURL と Authorization の両方が設定ファイルの値になり、/api/todos へのリクエストは 201 でした。テストの中で作った context には、この検証環境(1.63.0)では設定ファイルの use が引き継がれます。公式ドキュメントの API テストの説明には、この引き継ぎについての記述は見当たりませんでした。

トークンを外すには、空のヘッダーを明示します。次の2つの書き方は、どちらも auth=なし で送られ、401 が返りました。

ts
// newContext() で、ヘッダーを空にして上書きする
const ctx = await playwrightRequest.newContext({ extraHTTPHeaders: {} });

// describe の中だけ、request フィクスチャのヘッダーを空にする
test.describe('トークンなし', () => {
  test.use({ extraHTTPHeaders: {} });
  test('request フィクスチャ', async ({ request }) => {
    const res = await request.post('/api/todos', { data: { title: 'x' } });
    expect(res.status()).toBe(401);
  });
});

newContext() で作った context は、使い終わったら dispose() で片付けます。応答はメモリに残るためです(APIRequestContext の説明の dispose)。

画面のテストと組み合わせる

request と page は、同じテストの中で一緒に受け取れます。API で Todo を作り、画面に出ることを確かめてから、API で消すテストです。

ts
// tests/ui.spec.ts
import { test, expect } from '@playwright/test';

test('API で作った Todo が画面に出る', async ({ request, page }) => {
  const res = await request.post('/api/todos', { data: { title: '画面で確かめる' } });
  await expect(res).toBeOK();
  const todo = await res.json();

  await page.goto('/');
  await expect(page.getByRole('listitem').filter({ hasText: '画面で確かめる' })).toBeVisible();

  await request.delete(`/api/todos/${todo.id}`);
});

API でデータを用意したこのテストは、163ミリ秒で通りました。

ログインを API で済ませてから画面を開きたいときは、どちらの request を使うかで結果が変わります。page.request は、ブラウザのコンテキストと同じ Cookie を使います。request フィクスチャは、自分だけの Cookie を持つ別の context です(APIRequestContext の説明)。

ts
test('page.request でログインすると、ページにも Cookie が入る', async ({ page }) => {
  const login = await page.request.post('/login', { form: { user: 'alice', password: 'secret' } });
  await expect(login).toBeOK();
  await page.goto('/api/me');
  await expect(page.locator('body')).toHaveText('{"user":"alice"}');
});

test('request フィクスチャでログインしても、ページには Cookie が入らない', async ({ request, page }) => {
  await request.post('/login', { form: { user: 'alice', password: 'secret' } });
  await page.goto('/api/me');
  await expect(page.locator('body')).toHaveText('{"error":"not logged in"}');
});

記事のコードでは省きましたが、ログインのあとに page.context().cookies() でブラウザの Cookie を表示すると、page.request のときは [ 'sid' ]、request フィクスチャのときは [] でした。2つのテストはどちらも通っています。

page.request でログインした場合は、page.request と画面が同じ Cookie(sid あり)を使い、画面で開いた /api/me にもユーザーが返る。request フィクスチャでログインした場合は、request 側にだけ sid があり、ブラウザのコンテキストの Cookie はなしで、画面で開いた /api/me は not logged in になる
ログインに使う request の違いと、ブラウザの Cookie

画面のテストの前にログインを済ませるなら page.request を使います。API だけをテストするときは、テストごとに状態がまっさらになる request フィクスチャのほうが、前のテストの影響を受けません。

​Posted by 86