Playwrightのrequestで、APIを直接テストする方法
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 を用意し、次の設定にしました。
// 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() を呼びます。
// 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 ヘッダーが付いていたことを示します。
$ 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) では、数字の違いしか分かりません。
Error: expect(received).toBe(expected) // Object.is equality
Expected: 200
Received: 404
…(以下略)
await expect(res).toBeOK() では、送ったリクエストのヘッダーと、返ってきた本文まで表示されました。
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 になります。
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 だけを渡すテストを書きました。
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 が返りました。
// 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 で消すテストです。
// 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 の説明)。
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 を使います。API だけをテストするときは、テストごとに状態がまっさらになる request フィクスチャのほうが、前のテストの影響を受けません。





