Playwrightで、ドラッグアンドドロップをテストする方法

​​Playwright​E2Eテスト,TypeScript

Playwright では、locator.dragTo() を使うと、要素をつかんで別の要素の上に落とす操作を1行で書けます。カンバンボードでカードを「完了」の列へ移す、リストの項目をつかんで並べ替えるといった画面が、正しく動くかを自動で確かめたいときに使います。

ただ、私が検証用に作った、ポインターの動きを追う並べ替えリストでは、dragTo() をそのまま呼ぶだけでは並び順が変わりませんでした。私は検証環境で、ドラッグで操作する画面を作り方を変えて2種類用意し、テストの結果とイベントの回数を記録しました。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4、@playwright/test 1.63.0 です。ブラウザは Playwright 用の Chromium だけで、ページは Node.js の http モジュールで書いた小さなサーバーから配信しました。Firefox・WebKit、Windows・macOS、タッチ操作、SortableJS や dnd-kit などのライブラリで作った画面では試していません。

試した2種類の画面

1つ目は、HTML の Drag and Drop API で作ったタスクボードです。カードに draggable="true" を付け、dragstart でカードの ID を dataTransfer に入れます。列のほうでは dragover で preventDefault() を呼び、drop でカードを列に移して、role="status" の段落に、カード名と列名を入れた文(例:「請求書を送る」を「完了」に移しました)を出します。列は <section aria-label="完了"> です。

2つ目は、Pointer Events(pointerdown・pointermove・pointerup)で作った並べ替えリストです。HTML の Drag and Drop API を使わず、ポインターの動きを自分で追いかける作りです。

js
document.addEventListener('pointermove', (e) => {
  if (!dragging) return;
  pointerMoves++;
  if (!active && Math.abs(e.clientY - startY) < 5) return;
  if (!active) {
    // 5px 以上動いたら、ドラッグを始めたと判定する(この移動では並べ替えない)
    active = true;
    dragging.classList.add('dragging');
    return;
  }
  // ポインターの下の項目の、上半分なら前に、下半分なら後ろに入れる
  for (const li of list.children) {
    if (li === dragging) continue;
    const r = li.getBoundingClientRect();
    if (e.clientY >= r.top && e.clientY <= r.bottom) {
      if (e.clientY < r.top + r.height / 2) li.before(dragging); else li.after(dragging);
      break;
    }
  }
});

クリックとドラッグを区別するために、5px 以上動いたときに「ドラッグを始めた」と判定し、その次の pointermove から並べ替えます。pointermove が届いた回数は pointerMoves で数えています。

カードを別の列に移す

公式ドキュメントの、ドラッグアンドドロップの説明にあるとおり、つかむ要素のロケーターで dragTo() を呼び、落とす先のロケーターを渡します。

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

test('カードを別の列にドラッグする', async ({ page }) => {
  await page.goto('/');
  const card = page.getByText('請求書を送る');
  const done = page.getByRole('region', { name: '完了' });

  await card.dragTo(done);

  await expect(done.getByText('請求書を送る')).toBeVisible();
  await expect(page.locator('#board-status')).toHaveText('「請求書を送る」を「完了」に移しました');
});

テストは通りました。ページではイベントの回数を window.counts に数えていて、テストの最後に console.log で出しました。

text
counts {"dragstart":1,"dragenter":1,"dragover":1,"drop":1,"dragend":1}

公式ドキュメントによると、dragTo() は、つかむ要素の上にマウスを動かし、左ボタンを押し、落とす先までマウスを動かして、ボタンを離します。draggable の要素に対してこの操作をすると、Chromium では、数えた5種類(dragstart・dragenter・dragover・drop・dragend)が1回ずつ届きました。

確かめるときは、ドロップのあとの結果を見ます。ここでは「完了」の列の中にカードがあること(done.getByText(...))と、画面に出た文を確かめました。

並べ替えは、steps を付けないと動かなかった

並べ替えリストで、「りんご」を「もも」の下半分に落とすテストを書きました。期待する並び順は「みかん、ぶどう、もも、りんご」です。

ts
test('steps を付けずに並べ替える', async ({ page }) => {
  await page.goto('/');
  const list = page.getByRole('list', { name: '優先順位' });
  await list.getByText('りんご').dragTo(list.getByText('もも'), { targetPosition: { x: 20, y: 35 } });
  await expect(list.getByRole('listitem')).toHaveText(['みかん', 'ぶどう', 'もも', 'りんご'], { timeout: 2000 });
});

このテストは落ちました。並び順が、ドラッグの前のままです。

text
    Error: expect(locator).toHaveText(expected) failed
    Locator: getByRole('list', { name: '優先順位' }).getByRole('listitem')
    Timeout: 2000ms
    - Expected  - 1
    + Received  + 1
      Array [
    +   "りんご",
        "みかん",
        "ぶどう",
        "もも",
    -   "りんご",
      ]

原因は、マウスを動かす回数です。dragTo() の API リファレンスによると、steps オプションの初期値は 1 で、ボタンを押してから離すまでの間に送る mousemove は、落とす先での1回だけです。このリストは、1回目の pointermove を「ドラッグを始めた」判定に使い、並べ替えはしません。そのため、1回目の移動で終わると並び順が変わりません。

targetPosition はそのままにして、steps だけを 1・2・5・20 に変えて同じ操作をし、ページに届いた pointermove の回数と並び順を出しました。

steps pointermove の回数 並び順
1 1 りんご、みかん、ぶどう、もも
2 2 みかん、ぶどう、もも、りんご
5 5 みかん、ぶどう、もも、りんご
20 20 みかん、ぶどう、もも、りんご

pointermove は、steps に渡した数だけ届きました。2回以上動かせば、このリストの並び順が変わります。このリストのように、最初の移動をドラッグの開始の判定に使う画面をテストするときは、steps に 2 以上の数を渡します。下の GIF は、page.mouse.move() でマウスを20回に分けて動かし、その様子を撮ったものです。

並べ替えリストで、カーソルが「りんご」をつかんで下へ動かし、離すと「りんご」がいちばん下に移って、並び順の文の背景が一瞬ピンクになる。続けて「もも」をいちばん上へ動かす
マウスを20回に分けて動かし、項目を2回並べ替える様子

落とす位置を targetPosition で決める

このリストは、ポインターが項目の上半分にあれば前に、下半分にあれば後ろに入れます。targetPosition で、落とす先の要素の左上からの位置を指定すると、どちらに入るかをテストで決められます。

ts
test('りんごを、ぶどうの下半分に落とす', async ({ page }) => {
  await page.goto('/');
  const list = page.getByRole('list', { name: '優先順位' });
  const grape = list.getByText('ぶどう');
  const box = await grape.boundingBox();
  await list.getByText('りんご').dragTo(grape, {
    targetPosition: { x: 20, y: box!.height - 5 },
    steps: 5,
  });
  await expect(list.getByRole('listitem')).toHaveText(['みかん', 'ぶどう', 'りんご', 'もも']);
});

test('りんごを、ぶどうの上半分に落とす', async ({ page }) => {
  await page.goto('/');
  const list = page.getByRole('list', { name: '優先順位' });
  await list.getByText('りんご').dragTo(list.getByText('ぶどう'), {
    targetPosition: { x: 20, y: 5 },
    steps: 5,
  });
  await expect(list.getByRole('listitem')).toHaveText(['みかん', 'りんご', 'ぶどう', 'もも']);
});

どちらのテストも通りました。下半分に落とすと「ぶどう」の後ろに、上半分に落とすと「ぶどう」の前に入ります。

steps: 5 はそのままにして、targetPosition だけを外した場合も試しました。「ぶどう」の項目は高さが 46px、上端の y 座標が 429.75px で、pointerup が届いた位置の y 座標は 452.75px でした。ちょうど真ん中(429.75 + 23)です。

text
grape box {"x":16,"y":429.75,"width":240,"height":46}
pointerup clientY 452.75
center みかん,ぶどう,りんご,もも

このリストの判定では真ん中は下半分に入るので、「ぶどう」の後ろに入りました。API リファレンスには、位置を指定しないときは「要素の見えている、どこかの点」を使うとあります。今回は真ん中でしたが、真ん中を境に結果が変わる画面では、targetPosition で位置をはっきり決めておくほうが、何を確かめているテストかが読み手にも伝わります。

イベントの回数を見ながら、手でドラッグする

公式ドキュメントの、手でドラッグする方法の説明には、dragTo() の代わりに、hover()・mouse.down()・mouse.move()・mouse.up() を組み合わせて、ドラッグを1手ずつ書く方法も載っています。同じページの注意書きには、dragover に頼るページでは、すべてのブラウザで dragover を起こすために、マウスを2回以上動かす必要があると書かれています。そのため、落とす先の hover() を2回呼びます。

ts
test('手動でドラッグする', async ({ page }) => {
  await page.goto('/');
  const done = page.getByRole('region', { name: '完了' });
  await page.getByText('議事録をまとめる').hover();
  await page.mouse.down();
  await done.hover();
  await done.hover();
  await page.mouse.up();
  await expect(done.getByText('議事録をまとめる')).toBeVisible();
});

テストは通り、タスクボードの dragover は2回届きました。

text
manual {"dragstart":1,"dragenter":1,"dragover":2,"drop":1,"dragend":1}

タスクボードでも dragTo() の steps を 1・2・10 に変えて、イベントの回数と、dragenter が届いた列を出しました。Chromium では、steps が 1 でも dragover は1回届き、カードが「完了」の列に移ったこともテストで確かめられました。

text
steps 1 {"dragstart":1,"dragenter":1,"dragover":1,"drop":1,"dragend":1} dragenter の列 ["完了"]
steps 2 {"dragstart":1,"dragenter":1,"dragover":1,"drop":1,"dragend":1} dragenter の列 ["完了"]
steps 10 {"dragstart":1,"dragenter":2,"dragover":8,"drop":1,"dragend":1} dragenter の列 ["未着手","完了"]

steps が 10 のときは dragenter が2回になり、「完了」の前に、カードがもともとあった「未着手」の列にも届いていました。steps が 1 と 2 では、届いたのは「完了」の列だけです。

ページの外からファイルを落とすときは drop()

ここまでは、ページの中の要素をつかんで動かす操作でした。デスクトップからファイルを落とすような、ページの外から来るドロップには、ページの中につかむ要素がありません。そういうときは、Playwright 1.60 で追加された locator.drop() を使うと、ファイルを持たせたドロップの操作を、落とす先の要素に直接送れます。検証用のページには、dragover で preventDefault() を呼び、drop で受け取ったファイルの名前とサイズを #drop-status に出すドロップ先も用意しました。

ts
test('ページの外からファイルをドロップする', async ({ page }) => {
  await page.goto('/');
  await page.getByLabel('ファイルのドロップ先').drop({
    files: { name: 'note.txt', mimeType: 'text/plain', buffer: Buffer.from('hello') },
  });
  await expect(page.locator('#drop-status')).toHaveText('note.txt(5 バイト)を受け取りました');
});

テストは通り、ページは5バイトの note.txt を受け取りました。API リファレンスによると、drop() は落とす先に dragenter・dragover・drop を送り、dragover で preventDefault() が呼ばれなければ、ドロップを断られたとみなしてエラーにします。

​Posted by 86