Why your Playwright drop test never reaches the handler

The upload zone highlights when you drag a file over it by hand, but the Playwright test throws before the page shows a filename. Another test reaches the same zone and resolves cleanly, yet the component says that no data arrived. Those failures look alike in a CI report because both stop at the drop step, but they happen on opposite sides of the browser event boundary.

Follow the event contract before blaming the selector

The useful question is not whether drag and drop is flaky. It is whether the target rejected dragover, the handler asked for a MIME type that was never supplied, or the application failed after receiving a valid payload. Each branch leaves different evidence, and each needs a different fix.

Playwright has two drag-and-drop APIs with different jobs. locator.dragTo(target) starts with an element that already exists in the page. It moves the pointer to that source, presses the mouse, moves to the destination, and releases. That is the right shape for a card moving between kanban columns, a tile being reordered, or a slider handle being dragged.

locator.drop(payload) starts at the other boundary. There is no source locator. The test supplies files, string data, or both, as if the material came from outside the page. A desktop file dropped onto an upload panel fits that contract. So does a URL dropped onto an import target. The method was added in Playwright 1.60, which matters when a copied example fails at compile time in a suite pinned below that version.

The locator API describes the sequence precisely. Playwright constructs a synthetic DataTransfer in the page context and dispatches dragenter, dragover, and drop at the destination. Without a position option, it chooses a visible point in the element. A supplied position is relative to the top-left of the element's padding box. The resolved locator element remains event.target, so coordinates cannot redirect the synthetic event to one of its descendants.

One browser rule controls whether the sequence reaches drop. The destination must cancel dragover by calling preventDefault(). If it does not, Playwright treats the destination as having rejected the operation. It dispatches dragleave and throws. A drop listener on the element does not make the target acceptable by itself. Calling preventDefault() only inside that listener is too late because Playwright already made the acceptance decision during dragover.

That distinction explains a common failure in framework components. The JSX contains onDrop, so the test author assumes the zone accepts drops. The matching onDragOver prop is absent, is attached to a different element, or calls preventDefault() only when a predicate passes. The visible element can still look like a drop zone. Its name and CSS are irrelevant to the browser contract.

The payload has two channels. files accepts file paths or in-memory descriptors with name, mimeType, and buffer. Those names belong to Playwright's Node-side input. Page code receives browser File objects, where the corresponding properties are name, type, and size. It does not receive a buffer property, and it should read content through browser APIs such as file.text() or file.arrayBuffer() when the product needs it.

The data channel is a map from MIME type to string. A handler that calls getData("text/uri-list") will not find a value stored under text/plain. The MDN contract for getData() says a missing format returns an empty string. That outcome is not proof that Playwright lost the payload. It can simply mean the producer and consumer used different keys.

Browser-native file drags add a timing nuance. MDN documents a protected browser-managed drag data store whose files list is available during drop and paste, not during ordinary inspection outside those events. Do not project that rule onto the synthetic sequence created by locator.drop(). In Playwright 1.61, the method adds the supplied files to one script-owned DataTransfer and dispatches its events with that object, so the synthetic transfer can expose those files during dragover. Code that supports real desktop drags should still use dataTransfer.items for a coarse file-kind decision during dragover, then inspect the actual FileList during drop. A Playwright test should record what its handler received instead of claiming that the synthetic object reproduces the browser's protected store.

Playwright completing drop() proves a narrow set of facts. The locator resolved, the action reached an acceptable target, and Playwright dispatched the documented event sequence. Completion does not prove that the component read the intended format, accepted the file under product rules, updated state, generated a preview, or sent an upload request. Those are application outcomes and need their own assertions.

This separation also prevents a misleading workaround. Adding a timeout or retrying the test cannot repair a target that deliberately failed to cancel dragover. A longer wait changes nothing about an event listener that never accepts the operation. First identify the boundary that failed, then decide whether the test or the component owns the correction.

Read the failure at the boundary where it occurs

Start diagnosis with the line that failed. If the promise returned by locator.drop() rejects, inspect actionability and target acceptance before debugging parsing code that could not have run. If drop() resolves and the following expect fails, the destination accepted the operation. Move the investigation into MIME lookup, file handling, state updates, validation, or network work.

Do not make the exact Playwright error string part of the product oracle. The documented behavior is that the call throws when dragover is not canceled. Internal wording and call-log formatting can change between releases. await expect(zone.drop(payload)).rejects.toThrow() is enough for a focused negative test. For a positive test, let the thrown call fail naturally and preserve evidence that explains why it threw.

An event ledger is more useful than a screenshot for this problem. A screenshot can show a highlight class or a stale status message, but it cannot show the MIME keys in a DataTransfer. Record the event name, dataTransfer.types, safe file metadata, the string value the handler requested, and the application state produced by that handler. Keep the ledger small. Tokens, complete URLs with credentials, and full file contents do not belong in a CI artifact.

The following self-contained test creates a known-good destination and attaches its ledger to the Playwright report. It serves two purposes. It proves that the installed Playwright version can deliver the payload shape, and it demonstrates what to capture in a component-specific diagnostic. Every assertion can fail if the event sequence, MIME lookup, or file conversion changes.

import { expect, test } from "@playwright/test";

type LedgerRow = {
  event: string;
  types: string[];
  plain?: string;
  files?: Array<{ name: string; type: string; size: number }>;
};

test("records the external drop boundary", async ({ page }, testInfo) => {
  await page.setContent(`
    <main>
      <div data-testid="drop-zone">Drop a report</div>
      <output data-testid="result"></output>
    </main>
    <script>
      const zone = document.querySelector('[data-testid="drop-zone"]');
      const result = document.querySelector('[data-testid="result"]');
      const ledger = [];
      window.__dropLedger = ledger;

      for (const eventName of ['dragenter', 'dragover', 'dragleave', 'drop']) {
        zone.addEventListener(eventName, event => {
          if (eventName === 'dragover' || eventName === 'drop') {
            event.preventDefault();
          }

          const row = {
            event: eventName,
            types: Array.from(event.dataTransfer.types),
          };

          if (eventName === 'drop') {
            row.plain = event.dataTransfer.getData('text/plain');
            row.files = Array.from(event.dataTransfer.files, file => ({
              name: file.name,
              type: file.type,
              size: file.size,
            }));
            result.textContent = 'received';
          }

          ledger.push(row);
        });
      }
    </script>
  `);

  const fileBody = Buffer.from("case_id,status\n42,failed\n");
  await page.getByTestId("drop-zone").drop({
    data: { "text/plain": "nightly regression report" },
    files: {
      name: "results.csv",
      mimeType: "text/csv",
      buffer: fileBody,
    },
  });

  const ledger = await page.evaluate(
    () =>
      (window as Window & { __dropLedger: LedgerRow[] }).__dropLedger,
  );

  await testInfo.attach("drop-event-ledger", {
    body: Buffer.from(JSON.stringify(ledger, null, 2)),
    contentType: "application/json",
  });

  expect(ledger.map(row => row.event)).toEqual([
    "dragenter",
    "dragover",
    "drop",
  ]);
  expect(ledger.at(-1)).toMatchObject({
    plain: "nightly regression report",
    files: [
      { name: "results.csv", type: "text/csv", size: fileBody.length },
    ],
  });
  await expect(page.getByTestId("result")).toHaveText("received");
});

In an accepted run, that ledger ends with dragenter, dragover, and drop. In a rejected run, the useful shape is dragenter, dragover, then dragleave, followed by the thrown action. These are event names produced by the documented sequence, not timing measurements. If your own listener records only dragenter, check whether the target was replaced, navigation occurred, or another handler stopped propagation before assuming the payload is wrong.

Trace Viewer adds a second layer of evidence. A Playwright Test trace can show the action, its locator, DOM snapshots around it, the action log, console messages, and network requests. It does not automatically turn a browser DataTransfer into the domain-specific ledger your handler needs. Attach that ledger explicitly, as the example does, and use the trace to answer spatial and lifecycle questions: Was the intended zone visible? Did the locator resolve to the overlay or to the interactive child? Did the page rerender or navigate immediately after the action? Did an upload request start after the handler ran?

Run the smallest failing file in one browser and one worker before comparing the whole matrix. Serializing this diagnostic run removes unrelated interleaving from the report; it does not imply the finished test must remain serial forever.

pnpm exec playwright test tests/drop-zone.spec.ts --project=chromium --workers=1 --trace=on --reporter=html
pnpm exec playwright show-report

The command should preserve the original failure rather than manufacture a pass. Do not add --headed, retries, and a larger timeout all at once. Change one condition only when it answers a specific question. A headed-only pass points toward layout, hover behavior, or browser-mode differences. A single-worker-only pass points toward shared state or fixture collisions. Neither result proves that DataTransfer itself is unreliable.

The report line following drop() is also informative. A resolved action followed by Expected: "avatar.png" and Received: "No file selected" belongs to the application side. A failure on the action line with no drop entry in the ledger belongs to acceptance or actionability. A request that starts and returns a server error belongs beyond both of those boundaries. Keep those categories separate in test names so a dashboard does not collapse three owners into one generic “drag drop failed” bucket.

Work through three failures that look alike

The visible wrapper is not the element that accepts the drag

Consider an image uploader whose bordered wrapper fills the advertised drop area, while its dragover and drop listeners are attached only to a smaller child label. The test targets the wrapper because that is the element carrying the accessible name or test id. Playwright dispatches dragover at the resolved wrapper. Events bubble from a target toward its ancestors; they do not travel down into a descendant, so the child listener never calls preventDefault(). A person who releases the file directly over the child can still succeed, which makes the automated failure look like a payload problem.

The evidence is specific. The trace identifies the wrapper as the action target. A temporary listener on that wrapper records dragenter, dragover, and dragleave, while a marker in the child listener remains absent and no drop entry appears. Calling drop() on the child during diagnosis reaches the listener and proves the DOM-target mismatch, but that narrower locator may reduce coverage if the whole bordered area is supposed to accept a user's file. The product fix is to put acceptance on the element that owns the advertised drop region or deliberately delegate from that element.

Keep detailed file validation in drop even after the target topology is fixed. During dragover, accept a file-oriented transfer so the sequence can continue. During drop, inspect file.type, file.size, the extension if the product uses it, and eventually the contents. The following fixed component places both listeners on the element the test targets. Its two cases separate an accepted PNG from a PDF that reaches the application and receives a visible product rejection.

import { expect, test, type Page } from "@playwright/test";

async function mountImageDropZone(page: Page): Promise<void> {
  await page.setContent(`
    <div data-testid="image-zone">Drop an avatar</div>
    <output data-testid="image-status">Waiting</output>
    <script>
      const zone = document.querySelector('[data-testid="image-zone"]');
      const status = document.querySelector('[data-testid="image-status"]');

      zone.addEventListener('dragover', event => {
        const offersFile = Array.from(event.dataTransfer.items)
          .some(item => item.kind === 'file');
        if (offersFile) {
          event.preventDefault();
          status.textContent = 'Release to inspect';
        }
      });

      zone.addEventListener('drop', event => {
        event.preventDefault();
        const file = event.dataTransfer.files[0];

        if (!file || file.type !== 'image/png') {
          status.textContent = 'Only PNG images are accepted';
          return;
        }

        status.textContent = [file.name, file.type, file.size].join(':');
      });
    </script>
  `);
}

test("accepts a PNG after inspecting the File during drop", async ({ page }) => {
  await mountImageDropZone(page);

  await page.getByTestId("image-zone").drop({
    files: {
      name: "avatar.png",
      mimeType: "image/png",
      buffer: Buffer.from([0x89, 0x50, 0x4e, 0x47]),
    },
  });

  await expect(page.getByTestId("image-status")).toHaveText(
    "avatar.png:image/png:4",
  );
});

test("shows product validation for a delivered PDF", async ({ page }) => {
  await mountImageDropZone(page);

  await page.getByTestId("image-zone").drop({
    files: {
      name: "avatar.pdf",
      mimeType: "application/pdf",
      buffer: Buffer.from("%PDF fixture"),
    },
  });

  await expect(page.getByTestId("image-status")).toHaveText(
    "Only PNG images are accepted",
  );
});

This design has a cost. The target now accepts the initial file-kind drag before it knows whether the file meets every product rule. Users may see an active drop affordance for a file that will be rejected after release. You can refine the visual state with DataTransferItem.type when that metadata is available, but the authoritative validation still belongs in drop, where the actual File is accessible. The test should assert the visible rejection message so this trade-off remains intentional.

The action resolves, but getData() is empty

A URL-import component often accepts several text-like formats. The product handler requests text/uri-list, while the test supplies only text/plain. dragover is canceled, so Playwright dispatches drop and resolves. The handler then receives an empty string from getData("text/uri-list"), exactly as the platform specifies for a missing format.

The fastest diagnostic is to record both dataTransfer.types and the requested key. If the ledger says the offered type is text/plain and the requested type is text/uri-list, the transport is working. Changing locators or timeouts would attack the wrong layer. Decide whether the product is supposed to support the offered format. Then fix the producer, add an explicit fallback in the consumer, or preserve the rejection as a product rule.

This runnable example makes both contracts visible. One test deliberately supplies the wrong format and expects the component's controlled rejection. The other supplies the format the handler consumes and expects the imported host. Either assertion will fail if the component silently changes its accepted MIME type.

import { expect, test, type Page } from "@playwright/test";

async function mountUrlDropZone(page: Page): Promise<void> {
  await page.setContent(`
    <div data-testid="url-zone">Drop a URL</div>
    <output data-testid="url-status">Waiting</output>
    <script>
      const zone = document.querySelector('[data-testid="url-zone"]');
      const status = document.querySelector('[data-testid="url-status"]');

      zone.addEventListener('dragover', event => event.preventDefault());
      zone.addEventListener('drop', event => {
        event.preventDefault();
        const offered = Array.from(event.dataTransfer.types).join(', ');
        const value = event.dataTransfer.getData('text/uri-list').trim();

        if (!value) {
          status.textContent = 'Missing text/uri-list; offered ' + offered;
          return;
        }

        status.textContent = 'Imported ' + new URL(value).hostname;
      });
    </script>
  `);
}

test("reports the MIME mismatch instead of blaming the drop", async ({ page }) => {
  await mountUrlDropZone(page);

  await page.getByTestId("url-zone").drop({
    data: { "text/plain": "https://example.com/incidents/42" },
  });

  await expect(page.getByTestId("url-status")).toHaveText(
    "Missing text/uri-list; offered text/plain",
  );
});

test("imports a URL from the requested MIME format", async ({ page }) => {
  await mountUrlDropZone(page);

  await page.getByTestId("url-zone").drop({
    data: { "text/uri-list": "https://example.com/incidents/42" },
  });

  await expect(page.getByTestId("url-status")).toHaveText(
    "Imported example.com",
  );
});

Real text/uri-list data can contain more structure than one bare URL, including line breaks and comments. If the product claims to consume that format broadly, give its parser dedicated unit tests and use the browser test for the user-visible integration. If the product supports only a single URL string, state that narrower contract in its validation and test names. Do not call a single happy-path string complete coverage of the format.

Adding a fallback from text/uri-list to text/plain broadens compatibility, but it also broadens accepted input. The component must then validate that the plain text is a permitted URL rather than treating any string as navigation data. The security and product review belongs to the application change, not to the Playwright workaround.

The payload arrives, then application processing fails

The third failure begins with a successful event ledger. drop appears, the File metadata matches, and the action resolves. The UI still shows no imported records. At that point, the drag boundary is finished. The likely owners are file reading, parsing, schema validation, state management, a worker, or the request that persists the result.

A JSON report importer makes the distinction easy to see. Both valid and invalid JSON files are legitimate drag payloads. Playwright should deliver both. The application should import one and reject the other with a useful message. If a test expects locator.drop() itself to reject malformed JSON, it assigns application behavior to an automation API that does not parse the file.

import { expect, test, type Page } from "@playwright/test";

async function mountReportImporter(page: Page): Promise<void> {
  await page.setContent(`
    <div data-testid="report-zone">Drop a JSON report</div>
    <output data-testid="report-status">Waiting</output>
    <script>
      const zone = document.querySelector('[data-testid="report-zone"]');
      const status = document.querySelector('[data-testid="report-status"]');

      zone.addEventListener('dragover', event => event.preventDefault());
      zone.addEventListener('drop', async event => {
        event.preventDefault();
        const file = event.dataTransfer.files[0];

        if (!file) {
          status.textContent = 'Rejected report: no file';
          return;
        }

        try {
          const record = JSON.parse(await file.text());
          const validStatus = record.status === 'passed' || record.status === 'failed';
          if (typeof record.caseId !== 'string' || !validStatus) {
            status.textContent = 'Rejected report: invalid schema';
            return;
          }
          status.textContent = 'Imported ' + record.caseId + ': ' + record.status;
        } catch {
          status.textContent = 'Rejected report: invalid JSON';
        }
      });
    </script>
  `);
}

test("imports a delivered report after parsing it", async ({ page }) => {
  await mountReportImporter(page);

  await page.getByTestId("report-zone").drop({
    files: {
      name: "case-42.json",
      mimeType: "application/json",
      buffer: Buffer.from(JSON.stringify({ caseId: "CASE-42", status: "failed" })),
    },
  });

  await expect(page.getByTestId("report-status")).toHaveText(
    "Imported CASE-42: failed",
  );
});

test("rejects invalid content after the file is delivered", async ({ page }) => {
  await mountReportImporter(page);

  await page.getByTestId("report-zone").drop({
    files: {
      name: "broken.json",
      mimeType: "application/json",
      buffer: Buffer.from("{not valid json"),
    },
  });

  await expect(page.getByTestId("report-status")).toHaveText(
    "Rejected report: invalid JSON",
  );
});

Notice what makes the negative oracle real. If the component stops parsing, accepts malformed input, or changes its validation result, the assertion fails. The fixture is not checking a constant against another constant. It delivers bytes through the browser boundary and observes behavior produced from those bytes.

An upload request adds another stage. Wait for and assert that request only when the product sends one. A missing request after a correct drop ledger points toward application flow. A request with the wrong multipart field points toward serialization. A correct request followed by a server rejection belongs to the API contract. Avoid wrapping all of those outcomes in a catch around locator.drop(), because that catch cannot see failures that happen after the action resolves.

Fix the test without weakening its oracle

Once the failing boundary is known, make the smallest correction that preserves user behavior. When the component never cancels dragover, fix the component if it is intended to accept external drops. Do not inject a test-only listener that calls preventDefault() on production pages. That can make the automation pass while users still cannot drop a file through the real handler path.

If changing the component is outside the test's scope, report the defect with the ledger and keep the test failing or mark it with the team's documented issue process. A silent workaround is especially dangerous here because one line in the test can replace the acceptance decision the product was supposed to implement.

For a MIME mismatch, write down the producer and consumer keys next to each other. The test payload should use the key the product contract expects. When the product intentionally accepts fallbacks, test each accepted key in a separate case and keep one unsupported key as a negative case. A single test that supplies three formats at once can pass even if the handler always reads the wrong one, because another supplied format masks the defect.

For files, keep at least three assertion layers. First, assert delivery metadata that matters to the rule, usually name, type, size, or count. Second, assert the component's visible validation or preview. Third, assert the downstream effect when one exists, such as an imported row or upload request. Do not assert every File field just because it is available. Timestamps and platform-specific path details rarely belong to the user contract and make fixtures brittle.

The descriptor and browser object should remain visibly different in code review. Test code creates { name, mimeType, buffer }. Page code consumes file.name, file.type, file.size, and a browser read method. Naming a helper makeBrowserFile when it returns a Playwright descriptor blurs that boundary. Prefer a name such as makeDropFilePayload so a future maintainer does not try to access mimeType from the page.

Choose fixture storage from the behavior under test. An in-memory buffer is ideal for a tiny report whose bytes are meaningful to the assertion. It avoids current-working-directory mistakes and keeps the case self-contained. A checked-in file path is better when the file itself is a reviewed test asset, when encoding or binary structure matters, or when several tests share it. Either approach has cost: buffers can make large fixtures unreadable, while path fixtures add repository weight and path resolution work.

Keep negative tests at the correct layer. A target-acceptance negative case should omit preventDefault() and assert that drop() rejects. An unsupported-file case should accept dragover, receive the file, and assert product validation. A malformed-content case should receive and read the file, then assert parsing feedback. These tests may all display a red status in the product, but merging them would remove the evidence that assigns the failure.

Treat an actionability failure as a separate problem. An overlay, a detached target, a hidden element, or an unstable layout can prevent the action before the drag contract is exercised. In Playwright 1.61, locator.drop() offers position and timeout; neither turns an unreachable destination into a user-reachable one. Use the trace snapshot and locator inspection to correct the destination or synchronization.

Positioned drops need the same discipline. Supply position only when the resolved target itself interprets event coordinates to produce different behavior. A scheduling canvas might map coordinates to a time slot, so a position assertion is useful. The option does not retarget the event to a child element; choose that child with a locator when it owns the listener. A uniform upload panel gains nothing from fixed coordinates and becomes more sensitive to layout changes. The cost is maintenance each time padding, zoom, or responsive geometry changes.

Do not infer success from a CSS class alone. Many components add a highlight during dragenter or dragover, before a file is accepted and processed. A class assertion can pass even when drop never occurs. Assert it only when hover feedback is a product requirement, then continue to a result that proves the payload was handled.

Roll the change into CI without hiding the signal

Start migration with an inventory, not a bulk replacement. Find tests that manually construct DataTransfer, dispatch individual drag events, call dragTo() for an external file story, or use an <input> shortcut for a drop-zone requirement. Classify each by user interaction. Existing DOM source to DOM target remains a dragTo() case. External file or string data is a candidate for locator.drop(). A native file input controlled through the chooser may still be best tested with setInputFiles().

Before converting a large suite, add one contract test for each shared drop-zone component. Use a small in-memory payload, attach the event ledger, and assert a visible result. Then migrate product scenarios in groups. When a group fails, the shared contract test tells you whether the API works in the current browser project while the scenario evidence points to product-specific parsing or state.

Version rollout is a real constraint because locator.drop() requires Playwright 1.60 or later. Confirm the package version used by CI, the lockfile, and the browser binaries produced by the same installation. A developer with a newer global command cannot prove that the pinned CI dependency exposes the method. Treat a Playwright upgrade as its own change with release-note review and browser installation update, not as an incidental edit hidden inside a test rewrite.

The following configuration keeps a trace for a failed initial run without depending on retries. It also creates an HTML report that can display the JSON ledger attachment. Merge these options into the suite's existing projects and web-server setup instead of replacing product-specific configuration wholesale.

import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "./tests",
  outputDir: "test-results",
  forbidOnly: Boolean(process.env.CI),
  retries: 0,
  reporter: [
    ["line"],
    ["html", { open: "never", outputFolder: "playwright-report" }],
  ],
  use: {
    trace: "retain-on-failure",
    screenshot: "only-on-failure",
  },
  projects: [
    {
      name: "chromium",
      use: { ...devices["Desktop Chrome"] },
    },
  ],
});

retain-on-failure spends time recording every run and keeps the trace only for failures. That is a deliberate latency and storage trade-off. on-first-retry reduces tracing on initial passes, but it produces no trace when retries are disabled. Enabling a retry solely to collect evidence means the failing scenario runs again and can be reported as flaky if it passes. Decide which cost is acceptable instead of copying a trace mode without checking the retry policy.

Run migrated tests in the existing supported browser matrix after the Chromium diagnosis is stable. locator.drop() is designed as a cross-browser API, but the application handler, CSS hit area, file parser, and framework behavior can still differ. A single browser may be enough for a component contract in a constrained project. A customer-facing cross-browser promise deserves the configured Chromium, Firefox, and WebKit projects.

Parallel execution exposes fixture mistakes that a one-worker diagnosis hides. In-memory buffers are naturally isolated. Checked-in fixtures are safe when tests only read them. Generated files need a per-test output path rather than one shared filename. Event ledgers should live in test-scoped memory or attachments, not in a module-level array shared across cases.

Artifact retention needs a privacy review. Names, MIME types, sizes, event names, and controlled fixture identifiers are usually enough. A dropped customer export may contain email addresses, tokens, or proprietary records. Do not attach its raw contents merely because file.text() makes that easy. Build synthetic fixtures whose content is safe to retain and log only the fields required to distinguish parsing from transport.

Track the first migrated group for failure category, not an invented pass-rate target. Useful categories are actionability, rejected dragover, missing MIME key, incorrect file metadata, application validation, and downstream request failure. Those labels come from observed branches. They reveal whether the migration uncovered product defects, test assumptions, or CI setup problems without pretending that an unrun experiment produced measurements.

Know when a synthetic external drop is the wrong test

Do not use locator.drop() for a source element that users grab inside the page. A kanban card can set application state during dragstart, calculate movement during pointer events, and commit on drop. Supplying an external DataTransfer directly to the destination skips the source behavior. Use dragTo() or explicit mouse actions when the path and intermediate movement are part of the contract.

Avoid it when the requirement is the native file chooser. An <input type="file"> selected through a button is not an external drop, even if the same component supports both. setInputFiles() or the file chooser event addresses that path. One shared application function may process both inputs, but the browser entry points have different accessibility, cancellation, and UI behavior. Give them separate tests.

Do not claim that a synthetic drop proves operating-system integration. Playwright creates the DataTransfer in the page context. It does not automate dragging an icon from Finder, Explorer, or a Linux file manager across the browser chrome. If desktop-shell integration is the requirement, use a tool and environment capable of controlling that boundary, then keep a Playwright test for the web handler beneath it.

Directory drops need special care. Some products depend on browser-specific directory entry APIs or file-system handles rather than an ordinary list of files. locator.drop() documents files and string data, not every operating-system directory-drag behavior. Test the supported payload that the API can express, and cover directory traversal logic below the browser boundary unless official support for the exact interaction is confirmed.

A security feature may also require a real browser permission, download, or clipboard path. Similar-looking DataTransfer interfaces do not make those entry points interchangeable. Test the feature through the public interaction that creates the data. A direct synthetic payload is valuable for the receiving handler, but it cannot prove controls that occur before the handler sees anything.

Skip a full browser drop test for pure parsing branches that can be covered more directly. A CSV parser with dozens of malformed-row rules does not need dozens of browser sessions. Keep one or two browser cases that prove a delivered file reaches the parser and renders the outcome. Put the combinatorial input matrix in unit or service-level tests where failures point straight to the parser and run faster.

Manual event construction remains defensible on a suite pinned below Playwright 1.60, but it carries ownership cost. The test must create a DataTransfer, dispatch the correct sequence, pass a live handle into page events, and maintain browser differences. If the suite can upgrade safely, the first-class API removes much of that custom machinery. If it cannot, document why the helper exists and test the helper itself against a minimal destination.

Finally, do not rewrite a genuine product rejection into an automation pass. A component that refuses an unsupported type, an oversize file, or malformed content is working when that rule matches the requirement. The correct test delivers the payload successfully and asserts the rejection users see. The correct diagnostic records that drop occurred. Changing the payload until the UI turns green would erase the negative case rather than fix it.