📖 The Story: The Upload Zone That Broke in WebKit

A QA engineer was testing a new document upload feature. The component listened for dragenter, dragover, and drop events on a #dropzone div. On Chrome, the test worked fine — the engineer had written 12 lines of JavaScript that created a DataTransfer object, added a File to it, and dispatched the three events manually. The test passed, the PR merged, and the feature shipped.

Three days later, a customer reported the upload zone was completely broken on Safari. The engineer ran the same test on WebKit and it failed silently — the drop event fired, but the files array was empty. After two hours of debugging, they discovered that WebKit’s synthetic DataTransfer behaved differently: the file added via items.add() was not visible in the drop handler’s event.dataTransfer.files collection unless the event was dispatched with a specific browser-internal flag.

The engineer wrote a browser-specific workaround with feature detection, doubling the test code to 24 lines. It worked, but every time the team touched the upload component, the test broke in a new and creative way. The test became the most flaky in the suite.

The real problem was not the test code. It was that Playwright had no first-class drop API, so every team reinvented the same brittle wheel.

🎯 Why It Matters

🌍 Real World Example

A SaaS company ships a new email attachment uploader. The QA engineer writes a test that drags a 2 MB PDF from the desktop onto the upload zone. Before 1.60, this test required a Node script that read the PDF into a Buffer, wrapped it in a File object, built a DataTransfer, and dispatched three events — and it still failed on Safari. With locator.drop(), the entire test becomes a single line: await page.locator('#dropzone').drop({ files: { name: 'invoice.pdf', mimeType: 'application/pdf', buffer: pdfBuffer } }). It passes on all three browsers on the first run.

🧒 Explain Like I'm 10

Imagine you have a toy mailbox with a slot on top. You want to test that when you drop a letter into the slot, the mailbox eats it and shows a thank-you light.

Before, you had to pretend to be the postman: you made a fake letter, you made a fake hand, you told the hand to wiggle over the slot, and you told the letter to fall in. Sometimes the mailbox didn’t notice the letter because your fake hand wiggled wrong.

Now, Playwright gives you a magic button that says “drop this letter right here.” You press the button, and the letter appears inside the mailbox every single time, no wiggling needed.

🎓 Professional Explanation

The HTML5 drag-and-drop API is notoriously inconsistent across browsers. The DataTransfer object that carries the dragged payload has different initialization rules on Chromium, Firefox, and WebKit — particularly around whether files added via items.add() appear in the files collection during the drop event. Playwright 1.60’s locator.drop() abstracts this away by dispatching dragenter, dragover, and drop with a synthetic DataTransfer constructed inside the browser process, ensuring the payload is visible to the page’s event handlers on every engine.

The API accepts two payload shapes: files (an object with name, mimeType, and buffer) for file-drop scenarios, and data (a record of MIME-type to string) for clipboard-like data such as text/plain or text/uri-list. You can pass both in the same call if your drop zone accepts mixed content.

📊 The Flow

⚙️ The locator.drop() API

The API lives on the Locator class and accepts a single options object. You can drop files, clipboard-like data, or both. The synthetic DataTransfer is constructed inside the browser process, so the page’s drop handler sees the payload exactly as if a real user had dragged and dropped.

import { test } from class="tk-str">'@playwright/test';

test(class="tk-str">'upload a PDF via drag and drop', async ({ page }) => {
  await page.goto(class="tk-str">'https:class="tk-com">//app.example.com/upload');

  class=class="tk-str">"tk-com">// Drop a file onto the upload zone
  await page.locator(class="tk-str">'class="tk-com">#dropzone').drop({
    files: {
      name: class="tk-str">'invoice.pdf',
      mimeType: class="tk-str">'application/pdf',
      buffer: Buffer.from(class="tk-str">'mock pdf content'),
    },
  });

  await expect(page.getByText(class="tk-str">'invoice.pdf uploaded')).toBeVisible();
});

class=class="tk-str">"tk-com">// Drop clipboard-like data instead of files
test(class="tk-str">'drop a URL onto the rich text editor', async ({ page }) => {
  await page.goto(class="tk-str">'https:class="tk-com">//app.example.com/editor');

  await page.locator(class="tk-str">'.editor-area').drop({
    data: {
      class="tk-str">'text/plain': class="tk-str">'Check this out',
      class="tk-str">'text/uri-list': class="tk-str">'https:class="tk-com">//example.com/article',
    },
  });

  await expect(page.locator(class="tk-str">'.editor-area a')).toHaveAttribute(
    class="tk-str">'href', class="tk-str">'https:class="tk-com">//example.com/article'
  );
});

class=class="tk-str">"tk-com">// Drop multiple files at once
test(class="tk-str">'upload multiple files', async ({ page }) => {
  await page.goto(class="tk-str">'https:class="tk-com">//app.example.com/upload');

  await page.locator(class="tk-str">'class="tk-com">#dropzone').drop({
    files: [
      { name: class="tk-str">'a.pdf', mimeType: class="tk-str">'application/pdf', buffer: Buffer.from(class="tk-str">'a') },
      { name: class="tk-str">'b.png', mimeType: class="tk-str">'image/png', buffer: Buffer.from(class="tk-str">'b') },
      { name: class="tk-str">'c.txt', mimeType: class="tk-str">'text/plain', buffer: Buffer.from(class="tk-str">'c') },
    ],
  });

  await expect(page.getByText(class="tk-str">'3 files uploaded')).toBeVisible();
});

🔄 Before vs After

Before: Manual event synthesis (1.59 and earlier)

class=class="tk-str">"tk-com">// ~12 lines, browser-specific, brittle
await page.locator(class="tk-str">'class="tk-com">#dropzone').evaluate(async (el, fileContent) => {
  const dt = new DataTransfer();
  const file = new File([fileContent], class="tk-str">'note.txt', { type: class="tk-str">'text/plain' });
  dt.items.add(file);
  el.dispatchEvent(new DragEvent(class="tk-str">'dragenter', { dataTransfer: dt, bubbles: true }));
  el.dispatchEvent(new DragEvent(class="tk-str">'dragover',  { dataTransfer: dt, bubbles: true }));
  el.dispatchEvent(new DragEvent(class="tk-str">'drop',      { dataTransfer: dt, bubbles: true }));
}, class="tk-str">'hello');

After: locator.drop() (1.60+)

class=class="tk-str">"tk-com">// One line, cross-browser, no JS evaluation needed
await page.locator(class="tk-str">'class="tk-com">#dropzone').drop({
  files: {
    name: class="tk-str">'note.txt',
    mimeType: class="tk-str">'text/plain',
    buffer: Buffer.from(class="tk-str">'hello'),
  },
});

⚠️ Common Mistakes

Mistake 1: Forgetting to pass a Buffer, not a string

The buffer field expects a Node.js Buffer, not a plain string. If you pass buffer: 'hello', Playwright will silently send an empty file. Always wrap strings with Buffer.from('hello'), or read real files with fs.readFileSync('path/to/file').

class=class="tk-str">"tk-com">// WRONG
await page.locator(class="tk-str">'class="tk-com">#dropzone').drop({
  files: { name: class="tk-str">'note.txt', mimeType: class="tk-str">'text/plain', buffer: class="tk-str">'hello' }
});

class=class="tk-str">"tk-com">// CORRECT
await page.locator(class="tk-str">'class="tk-com">#dropzone').drop({
  files: { name: class="tk-str">'note.txt', mimeType: class="tk-str">'text/plain', buffer: Buffer.from(class="tk-str">'hello') }
});

Mistake 2: Expecting drag-move events to fire

locator.drop() dispatches exactly three events: dragenter, dragover, drop. It does not fire dragstart, drag, or dragend. If your test asserts that a “drag in progress” overlay appeared, it will fail. Use page.mouse for full drag-path tests.

Mistake 3: Using the wrong MIME type

If you pass mimeType: 'application/pdf' but the buffer contains plain text, some upload zones validate the MIME against the file content and reject the drop. Match the MIME to the actual buffer content, or use 'application/octet-stream' for raw binary.

✅ Best Practices

1. Always use Buffer.from() for inline file content — never pass raw strings to the buffer field.
2. Match the mimeType to the actual content to avoid server-side validation failures in your test environment.
3. Read real files with fs.readFileSync() when you need realistic file sizes for performance testing.
4. Use the data option for clipboard scenarios (rich text editors, URL droppers) instead of faking file objects.
5. Assert the upload UI reacted immediately after the drop — Playwright’s auto-waiting handles the async gap.

🏗️ Senior Engineer Deep Dive

Why the DataTransfer abstraction matters

The HTML5 drag-and-drop spec leaves DataTransfer initialization largely up to the browser. During a real user drag, the browser populates dataTransfer.files and dataTransfer.items internally. When you synthesize a DragEvent from JavaScript, you can only set dataTransfer via the constructor — and the items.add() method behaves differently across engines. WebKit, in particular, does not expose files added via items.add() in the files collection during the drop event. Playwright solves this by constructing the DataTransfer inside the browser process (via CDP for Chromium, marionette for Firefox, WIRelay for WebKit), bypassing the JavaScript sandbox entirely.

When to use drop() vs setInputFiles()

page.setInputFiles() is for traditional <input type="file"> elements. locator.drop() is for custom drop zones that listen for drag events. If your component has both — a hidden file input with a visible drop overlay — prefer setInputFiles() for reliability, and use drop() only when the component genuinely requires drag events.

💼 Interview Questions

🏋️ Practical Exercise

🚀 Mini Project

📝 Quiz

❓ FAQ

Q: Can I use locator.drop() to test drag-and-drop between two elements on the same page?

A: No. locator.drop() simulates an external drop (like dragging a file from the desktop). For internal element-to-element drag (like reordering list items), use the existing page.mouse API: await page.mouse.move(srcX, srcY); await page.mouse.down(); await page.mouse.move(dstX, dstY, { steps: 10 }); await page.mouse.up();.

Q: Does locator.drop() work with the old recordVideo option?

A: Yes. locator.drop() is independent of the video/screencast system. If you have video enabled, the drop will be visible in the recording. With the new 1.59+ screencast API, you can also add chapter markers around the drop for narration.

Q: Can I drop a file larger than available memory?

A: No. The buffer must fit in Node.js memory. For very large files, use a mock buffer of the correct size (Buffer.alloc(50 * 1024 * 1024) for a 50 MB placeholder) rather than reading the real file. The drop zone typically only checks the file name and size, not the actual content.

📦 Summary