Playwrightのdevicesでスマホ表示をテストする方法
Playwright の devices を使うと、Pixel 7 や iPhone 13 などの画面の大きさ、ユーザーエージェント、タッチ操作の有無をまとめて再現したブラウザでテストできます。設定ファイルにスマホ用のプロジェクトを1つ足すだけで、同じテストがデスクトップとスマホの両方で走ります。
レスポンシブデザインのページで「スマホの幅のときだけハンバーガーメニューが出て、タップすると開く」といった動きを、手でブラウザの幅を変えずに E2E テストで確かめたいときに使えます。
検証環境は Ubuntu 24.04、Node.js 22.23.4、@playwright/test 1.63.0 です。ブラウザは Chromium だけが入った環境で、WebKit(Safari のエンジン)と Firefox は使っていません。そのため iPhone の設定は、Chromium に切り替えて画面の大きさなどを確かめるところまでにしています。実機や Android のエミュレーターでの表示との比較、page.setViewportSize() でテストの途中に大きさを変える方法は試していません。
テストしたページ
検証用に、次のような小さなページを用意しました。
- 幅が 600px より広いときは、ヘッダーに「商品」「店舗」「お問い合わせ」のリンクが横に並ぶ
- 600px 以下のときは、リンクを隠して「メニュー」ボタンを出す。ボタンを押すとリンクが縦に並んで出て、
aria-expandedがtrueになる - ページの中に、
window.innerWidth、devicePixelRatio、(pointer: coarse)に合うか、ontouchstartがあるかを書き出す
<head> には、スマホ向けのページでふつう書く <meta name="viewport" content="width=device-width, initial-scale=1"> を入れています。
設定ファイルにスマホのプロジェクトを足す
devices は @playwright/test から読み込めます。プロジェクトの use に ...devices['Pixel 7'] のように展開して渡すと、そのプロジェクトのテストはその端末の設定で動きます。公式ドキュメントのエミュレーションのページにも、同じ書き方が載っています。
// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
testDir: './tests',
reporter: 'list',
use: { baseURL: 'http://localhost:3000' },
webServer: { command: 'node server.mjs', url: 'http://localhost:3000', reuseExistingServer: true },
projects: [
{ name: 'desktop', use: { ...devices['Desktop Chrome'] } },
{ name: 'pixel7', use: { ...devices['Pixel 7'] } },
{ name: 'iphone13', use: { ...devices['iPhone 13'] } },
],
});
devices の中身
devices は、端末の名前をキーにした設定のオブジェクトです。1.63.0 では 207 件が入っていて、iPhone 17 や Pixel 9、Galaxy S24 などもありました。Pixel 7 の中身を出すと、次のとおりです。
{
"userAgent": "Mozilla/5.0 (Linux; Android 14; Pixel 7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/153.0.8010.12 Mobile Safari/537.36",
"viewport": { "width": 412, "height": 839 },
"screen": { "width": 412, "height": 915 },
"deviceScaleFactor": 2.625,
"isMobile": true,
"hasTouch": true,
"defaultBrowserType": "chromium"
}
(実際の出力では viewport と screen の値も1つずつ改行されていたのを、1行にまとめています。)
主な値を比べると、次のようになります。
| 端末の名前 | viewport | deviceScaleFactor | isMobile | hasTouch | defaultBrowserType |
|---|---|---|---|---|---|
| Desktop Chrome | 1280 × 720 | 1 | false | false | chromium |
| Pixel 7 | 412 × 839 | 2.625 | true | true | chromium |
| Pixel 7 landscape | 863 × 360 | 2.625 | true | true | chromium |
| iPhone 13 | 390 × 664 | 3 | true | true | webkit |
viewport はページを表示する領域の大きさ、deviceScaleFactor は CSS の 1px あたりの画素の数です。isMobile は、公式の API の説明によると、meta viewport を考慮するかどうかと、タッチイベントを有効にするかどうかを決める値です。landscape が付いた名前は横向きの設定で、screen の幅と高さが入れ替わり、viewport も横長(863 × 360)になります。
同じテストを、デスクトップとスマホで実行する
テストは、プロジェクトごとに書き分ける必要はありません。最初は、テストに渡される isMobile を見て、確かめる内容を分けてみました。ファイルは tests/menu.spec.ts です。2つ目のテスト 端末の値をページから読む は、ページに書き出した値とユーザーエージェントを console.log で出すためのものです。
import { test, expect } from '@playwright/test';
test('画面の幅に合ったメニューが出る', async ({ page, isMobile }) => {
await page.goto('/');
const menuButton = page.getByRole('button', { name: 'メニュー' });
const shopLink = page.getByRole('link', { name: '店舗' });
if (isMobile) {
await expect(menuButton).toBeVisible();
await expect(shopLink).toBeHidden();
await menuButton.tap();
await expect(shopLink).toBeVisible();
await expect(menuButton).toHaveAttribute('aria-expanded', 'true');
} else {
await expect(menuButton).toBeHidden();
await expect(shopLink).toBeVisible();
}
});
test('端末の値をページから読む', async ({ page }, testInfo) => {
await page.goto('/');
const info = await page.locator('#info').textContent();
console.log(`[${testInfo.project.name}]\n${info}\nuserAgent: ${await page.evaluate(() => navigator.userAgent)}`);
});
tap() はタッチでの操作です。公式の API の説明にあるとおり、hasTouch が true のときに使えます。devices のスマホの設定には hasTouch: true が入っているので、そのまま使えました。
npx playwright test を実行すると、結果の各行に [desktop] や [pixel7] のようにプロジェクトの名前が付いて、同じテストがそれぞれの設定で走ります。端末の値をページから読む が出した値は、次のようになりました。
[desktop]
innerWidth x innerHeight: 1280 x 720
devicePixelRatio: 1
pointer coarse: false
ontouchstart: false
userAgent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/153.0.8010.12 Safari/537.36
[pixel7]
innerWidth x innerHeight: 412 x 839
devicePixelRatio: 2.625
pointer coarse: true
ontouchstart: true
userAgent: Mozilla/5.0 (Linux; Android 14; Pixel 7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/153.0.8010.12 Mobile Safari/537.36
devices['Pixel 7'] の値が、ページから見た表示の幅、画素の比率、ユーザーエージェントにそのまま出ています。matchMedia('(pointer: coarse)') も true になりました。

iPhone の設定は WebKit で起動する
一方、iphone13 のプロジェクトは、テストが始まる前に失敗しました。
✘ 5 [iphone13] › tests/menu.spec.ts:3:1 › 画面の幅に合ったメニューが出る (1ms)
✘ 6 [iphone13] › tests/menu.spec.ts:20:1 › 端末の値をページから読む (2ms)
Error: browserType.launch: Executable doesn't exist at /path/to/pw-browsers/webkit-2359/pw_run.sh
(パスは例示用の値に置き換えています。)
iPhone の設定は defaultBrowserType が webkit なので、プロジェクトで browserName を指定していなければ WebKit で起動します。WebKit を入れていない環境では、このように起動の段階で止まります。Safari のエンジンで確かめたいなら、npx playwright install webkit で WebKit を入れておく必要があります。
画面の大きさだけを確かめたい場合は、devices を展開したあとに browserName を書くと、ブラウザを切り替えられます。
{ name: 'iphone13-chromium', use: { ...devices['iPhone 13'], browserName: 'chromium' } },
このプロジェクトでは、表示の幅が 390 × 664、devicePixelRatio が 3、ユーザーエージェントが iPhone のものになり、テストは通りました。ただし表示しているのは Chromium なので、Safari での見た目や動きを確かめたことにはなりません。
横向きの設定で、isMobile での分け方が崩れた
Pixel 7 landscape のプロジェクトも足して実行すると、メニューのテストが失敗しました。
✘ 5 [pixel7-landscape] › tests/menu.spec.ts:3:1 › 画面の幅に合ったメニューが出る (5.1s)
Error: expect(locator).toBeVisible() failed
Locator: getByRole('button', { name: 'メニュー' })
Expected: visible
Timeout: 5000ms
Error: element(s) not found
横向きの Pixel 7 は、isMobile は true のままですが、表示の幅は 863px です。ページの CSS は 600px 以下でメニューのボタンを出すので、この幅ではボタンが出ません。テストは「スマホならボタンが出る」と考えていたので、ページとテストの前提が食い違っていました。
ページの見た目を決めているのは表示の幅なので、テストも page.viewportSize() の幅で分けるように直しました。ファイルは tests-fixed/menu.spec.ts で、設定ファイルのプロジェクトは desktop、pixel7、pixel7-landscape、iphone13-chromium の4つです。
import { test, expect } from '@playwright/test';
test('画面の幅に合ったメニューが出る', async ({ page }) => {
await page.goto('/');
const menuButton = page.getByRole('button', { name: 'メニュー' });
const shopLink = page.getByRole('link', { name: '店舗' });
const narrow = page.viewportSize()!.width <= 600;
if (narrow) {
await expect(menuButton).toBeVisible();
await expect(shopLink).toBeHidden();
await menuButton.tap();
await expect(shopLink).toBeVisible();
await expect(menuButton).toHaveAttribute('aria-expanded', 'true');
} else {
await expect(menuButton).toBeHidden();
await expect(shopLink).toBeVisible();
}
});
これで、4つのプロジェクトがすべて通りました。
Running 4 tests using 2 workers
✓ 2 [desktop] › tests-fixed/menu.spec.ts:3:1 › 画面の幅に合ったメニューが出る (131ms)
✓ 1 [pixel7] › tests-fixed/menu.spec.ts:3:1 › 画面の幅に合ったメニューが出る (215ms)
✓ 3 [pixel7-landscape] › tests-fixed/menu.spec.ts:3:1 › 画面の幅に合ったメニューが出る (178ms)
✓ 4 [iphone13-chromium] › tests-fixed/menu.spec.ts:3:1 › 画面の幅に合ったメニューが出る (193ms)
4 passed (1.6s)
公式ドキュメントのプロジェクトの説明にあるとおり、--project でプロジェクトの名前を指定すると、そのプロジェクトだけを実行できます。スマホのプロジェクトだけを流したいときに使えます。
npx playwright test --project=pixel7
viewport だけを変えた場合との違い
devices を使わずに、プロジェクトの use に viewport: { width: 412, height: 839 } だけを指定しても、表示の幅は 412px になります。表示の幅に違いが出たのは、meta viewport を書いていないページでした。同じページから meta viewport の行だけを消したものを用意して、比べました。
| 設定 | meta viewport | innerWidth × innerHeight | devicePixelRatio | タッチ | メニューのボタン |
|---|---|---|---|---|---|
| viewport だけ | あり | 412 × 839 | 1 | なし | 表示 |
| viewport だけ | なし | 412 × 839 | 1 | なし | 表示 |
| Pixel 7 | あり | 412 × 839 | 2.625 | あり | 表示 |
| Pixel 7 | なし | 981 × 1996 | 2.625 | あり | 非表示 |
(「タッチ」は、(pointer: coarse) と ontouchstart がどちらも true だったかどうかです。)
viewport だけの設定では isMobile が初期値の false なので、meta viewport があってもなくても、幅は 412px のままでした。Pixel 7 の設定では meta viewport が考慮されるため、書いていないページは 981px の幅で描かれ、全体が縮んで表示されました。

viewport だけの設定では、この違いに気づけません。devices の設定なら、meta viewport の書き忘れのように、isMobile が true のときにだけ出る違いもテストで見つけられます。
test.describe の中で devices を使うとエラーになる
設定ファイルではなく、テストファイルの一部だけをスマホの設定にしたいこともあります。test.describe の中で test.use({ ...devices['Pixel 7'] }) と書くと、テストを始める前に次のエラーで止まりました。
Cannot use({ defaultBrowserType }) in a describe group, because it forces a new worker.
Make it top-level in the test file or put in the configuration file.
devices の値に defaultBrowserType が含まれているためで、defaultBrowserType が chromium の Pixel 7 でも同じでした。メッセージのとおり、ファイルの先頭(どの test.describe にも入れない位置)に test.use({ ...devices['Pixel 7'] }) を書くと、テストは通りました。
test.describe の中で使いたいときは、defaultBrowserType を取り除いてから渡すと通りました。
import { test, expect, devices } from '@playwright/test';
const { defaultBrowserType, ...pixel7 } = devices['Pixel 7'];
test.describe('スマホ', () => {
test.use(pixel7);
test('メニューのボタンが出る', async ({ page }) => {
await page.goto('/');
await expect(page.getByRole('button', { name: 'メニュー' })).toBeVisible();
});
});
スマホ用のテストが多いなら、設定ファイルにプロジェクトとして足すほうが、どの端末の設定で動いたかが、結果の各行に付くプロジェクト名で分かります。





