Skip to content

ever-co/ever-works / .agents/skills/playwright-best-practices

playwright-best-practices

Verified

Use when writing Playwright tests, fixing flaky tests, debugging failures, implementing Page Object Model, configuring CI/CD, optimizing performance, mocking APIs, handling authentication or OAuth, testing accessibility (axe-core), file uploads/downloads, date/time mocking, WebSockets, geolocation, permissions, multi-tab/popup flows, mobile/responsive layouts, touch gestures, GraphQL, error handling, offline mode, multi-user collaboration, third-party services (payments, email verification), console error monitoring, global setup/teardown, test annotations (skip, fixme, slow), test tags (@smoke, @fast, @critical, filtering with --grep), project dependencies, security testing (XSS, CSRF, auth), performance budgets (Web Vitals, Lighthouse), iframes, component testing, canvas/WebGL, service workers/PWA, test coverage, i18n/localization, Electron apps, or browser extension testing. Covers E2E, component, API, visual, accessibility, security, Electron, and extension testing.

FileKindSize
LICENSE.mdmarkdown1.0 KB
README.mdmarkdown9.9 KB
SKILL.mdskill md25.7 KB
advanced/authentication-flows.mdmarkdown10.4 KB
advanced/authentication.mdmarkdown29.4 KB
advanced/clock-mocking.mdmarkdown9.4 KB
advanced/mobile-testing.mdmarkdown10.3 KB
advanced/multi-context.mdmarkdown8.2 KB
advanced/multi-user.mdmarkdown10.9 KB
advanced/network-advanced.mdmarkdown10.1 KB
advanced/third-party.mdmarkdown11.1 KB
architecture/pom-vs-fixtures.mdmarkdown11.4 KB
architecture/test-architecture.mdmarkdown14.3 KB
architecture/when-to-mock.mdmarkdown11.9 KB
browser-apis/browser-apis.mdmarkdown10.1 KB
browser-apis/iframes.mdmarkdown11.1 KB
browser-apis/service-workers.mdmarkdown13.1 KB
browser-apis/websockets.mdmarkdown9.9 KB
core/annotations.mdmarkdown10.4 KB
core/assertions-waiting.mdmarkdown9.1 KB
core/configuration.mdmarkdown13.7 KB
core/fixtures-hooks.mdmarkdown11.2 KB
core/global-setup.mdmarkdown12.4 KB
core/locators.mdmarkdown6.4 KB
core/page-object-model.mdmarkdown7.7 KB
core/projects-dependencies.mdmarkdown8.1 KB
core/test-data.mdmarkdown11.3 KB
core/test-suite-structure.mdmarkdown9.1 KB
core/test-tags.mdmarkdown6.7 KB
debugging/console-errors.mdmarkdown9.3 KB
debugging/debugging.mdmarkdown14.7 KB
debugging/error-testing.mdmarkdown9.2 KB
debugging/flaky-tests.mdmarkdown14.5 KB
frameworks/angular.mdmarkdown18.9 KB
frameworks/nextjs.mdmarkdown13.4 KB
frameworks/react.mdmarkdown17.5 KB
frameworks/vue.mdmarkdown17.3 KB
infrastructure-ci-cd/ci-cd.mdmarkdown10.4 KB
infrastructure-ci-cd/docker.mdmarkdown7.0 KB
infrastructure-ci-cd/github-actions.mdmarkdown15.1 KB
infrastructure-ci-cd/gitlab.mdmarkdown10.9 KB
infrastructure-ci-cd/other-providers.mdmarkdown14.2 KB
infrastructure-ci-cd/parallel-sharding.mdmarkdown11.6 KB
infrastructure-ci-cd/performance.mdmarkdown11.3 KB
infrastructure-ci-cd/reporting.mdmarkdown11.4 KB
infrastructure-ci-cd/test-coverage.mdmarkdown12.0 KB
testing-patterns/accessibility.mdmarkdown8.7 KB
testing-patterns/api-testing.mdmarkdown23.5 KB
testing-patterns/browser-extensions.mdmarkdown13.0 KB
testing-patterns/canvas-webgl.mdmarkdown12.3 KB
testing-patterns/component-testing.mdmarkdown11.0 KB
testing-patterns/drag-drop.mdmarkdown17.4 KB
testing-patterns/electron.mdmarkdown12.8 KB
testing-patterns/file-operations.mdmarkdown10.0 KB
testing-patterns/file-upload-download.mdmarkdown16.5 KB
testing-patterns/forms-validation.mdmarkdown21.3 KB
testing-patterns/graphql-testing.mdmarkdown8.6 KB
testing-patterns/i18n.mdmarkdown12.3 KB
testing-patterns/performance-testing.mdmarkdown11.5 KB
testing-patterns/security-testing.mdmarkdown11.5 KB
testing-patterns/visual-regression.mdmarkdown18.4 KB

testing-patterns/drag-drop.md

View on GitHub
# Drag and Drop Testing

## Table of Contents

1. [Kanban Board (Cross-Column Movement)](#kanban-board-cross-column-movement)
2. [Sortable Lists (Reordering)](#sortable-lists-reordering)
3. [Native HTML5 Drag and Drop](#native-html5-drag-and-drop)
4. [File Drop Zone](#file-drop-zone)
5. [Canvas Coordinate-Based Dragging](#canvas-coordinate-based-dragging)
6. [Custom Drag Preview](#custom-drag-preview)
7. [Variations](#variations)
8. [Tips](#tips)

> **When to use**: Testing drag-and-drop interactions — sortable lists, kanban boards, file drop zones, or repositionable elements.

---

## Kanban Board (Cross-Column Movement)

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

test('moves card between columns', async ({ page }) => {
	await page.goto('/board');

	const backlog = page.locator('[data-column="backlog"]');
	const active = page.locator('[data-column="active"]');

	const ticket = backlog.getByText('Update API docs');
	await expect(ticket).toBeVisible();

	const backlogCountBefore = await backlog.getByRole('article').count();
	const activeCountBefore = await active.getByRole('article').count();

	await ticket.dragTo(active);

	await expect(active.getByText('Update API docs')).toBeVisible();
	await expect(backlog.getByText('Update API docs')).not.toBeVisible();

	await expect(backlog.getByRole('article')).toHaveCount(backlogCountBefore - 1);
	await expect(active.getByRole('article')).toHaveCount(activeCountBefore + 1);
});

test('progresses card through workflow stages', async ({ page }) => {
	await page.goto('/board');

	const cols = {
		backlog: page.locator('[data-column="backlog"]'),
		active: page.locator('[data-column="active"]'),
		review: page.locator('[data-column="review"]'),
		complete: page.locator('[data-column="complete"]')
	};

	await cols.backlog.getByText('Update API docs').dragTo(cols.active);
	await expect(cols.active.getByText('Update API docs')).toBeVisible();

	await cols.active.getByText('Update API docs').dragTo(cols.review);
	await expect(cols.review.getByText('Update API docs')).toBeVisible();

	await cols.review.getByText('Update API docs').dragTo(cols.complete);
	await expect(cols.complete.getByText('Update API docs')).toBeVisible();

	await expect(cols.backlog.getByText('Update API docs')).not.toBeVisible();
	await expect(cols.active.getByText('Update API docs')).not.toBeVisible();
	await expect(cols.review.getByText('Update API docs')).not.toBeVisible();
});

test('reorders cards within same column', async ({ page }) => {
	await page.goto('/board');

	const backlog = page.locator('[data-column="backlog"]');

	const itemX = backlog.getByRole('article').filter({ hasText: 'Item X' });
	const itemZ = backlog.getByRole('article').filter({ hasText: 'Item Z' });

	await itemZ.dragTo(itemX);

	const cards = await backlog.getByRole('article').allTextContents();
	expect(cards.indexOf('Item Z')).toBeLessThan(cards.indexOf('Item X'));
});

test('verifies drag persists via API', async ({ page }) => {
	await page.goto('/board');

	const backlog = page.locator('[data-column="backlog"]');
	const active = page.locator('[data-column="active"]');

	const responsePromise = page.waitForResponse(
		(r) => r.url().includes('/api/tickets') && r.request().method() === 'PATCH'
	);

	await backlog.getByText('Update API docs').dragTo(active);

	const response = await responsePromise;
	expect(response.status()).toBe(200);

	const body = await response.json();
	expect(body.column).toBe('active');

	await page.reload();
	await expect(active.getByText('Update API docs')).toBeVisible();
});
```

---

## Sortable Lists (Reordering)

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

test('reorders list items', async ({ page }) => {
	await page.goto('/priorities');

	const list = page.getByRole('list', { name: 'Priority list' });

	const initial = await list.getByRole('listitem').allTextContents();
	expect(initial[0]).toContain('Priority A');
	expect(initial[1]).toContain('Priority B');
	expect(initial[2]).toContain('Priority C');

	const priorityC = list.getByRole('listitem').filter({ hasText: 'Priority C' });
	const priorityA = list.getByRole('listitem').filter({ hasText: 'Priority A' });

	await priorityC.dragTo(priorityA);

	const reordered = await list.getByRole('listitem').allTextContents();
	expect(reordered[0]).toContain('Priority C');
	expect(reordered[1]).toContain('Priority A');
	expect(reordered[2]).toContain('Priority B');
});

test('reorders via drag handle', async ({ page }) => {
	await page.goto('/priorities');

	const list = page.getByRole('list', { name: 'Priority list' });

	const handle = list
		.getByRole('listitem')
		.filter({ hasText: 'Priority C' })
		.getByRole('button', { name: /drag|reorder|grip/i });

	const target = list.getByRole('listitem').filter({ hasText: 'Priority A' });

	await handle.dragTo(target);

	const items = await list.getByRole('listitem').allTextContents();
	expect(items[0]).toContain('Priority C');
});

test('reorder persists after reload', async ({ page }) => {
	await page.goto('/priorities');

	const list = page.getByRole('list', { name: 'Priority list' });

	const priorityC = list.getByRole('listitem').filter({ hasText: 'Priority C' });
	const priorityA = list.getByRole('listitem').filter({ hasText: 'Priority A' });

	await priorityC.dragTo(priorityA);

	await page.waitForResponse(
		(response) => response.url().includes('/api/priorities/reorder') && response.status() === 200
	);

	await page.reload();

	const items = await list.getByRole('listitem').allTextContents();
	expect(items[0]).toContain('Priority C');
	expect(items[1]).toContain('Priority A');
	expect(items[2]).toContain('Priority B');
});
```

### Incremental Mouse Movement for Custom Libraries

Some drag libraries (react-beautiful-dnd, dnd-kit) require incremental mouse movements:

```typescript
test('reorders with incremental mouse movements', async ({ page }) => {
	await page.goto('/priorities');

	const list = page.getByRole('list', { name: 'Priority list' });
	const source = list.getByRole('listitem').filter({ hasText: 'Priority C' });
	const target = list.getByRole('listitem').filter({ hasText: 'Priority A' });

	const sourceBox = await source.boundingBox();
	const targetBox = await target.boundingBox();

	await source.hover();
	await page.mouse.down();

	const steps = 10;
	for (let i = 1; i <= steps; i++) {
		await page.mouse.move(
			sourceBox!.x + sourceBox!.width / 2,
			sourceBox!.y + (targetBox!.y - sourceBox!.y) * (i / steps),
			{ steps: 1 }
		);
	}

	await page.mouse.up();

	const items = await list.getByRole('listitem').allTextContents();
	expect(items[0]).toContain('Priority C');
});
```

---

## Native HTML5 Drag and Drop

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

test('drags item to drop zone', async ({ page }) => {
	await page.goto('/drag-example');

	const source = page.getByText('Movable Element');
	const dropArea = page.locator('#target-zone');

	await expect(source).toBeVisible();
	await expect(dropArea).not.toContainText('Movable Element');

	await source.dragTo(dropArea);

	await expect(dropArea).toContainText('Movable Element');
});

test('drags between zones', async ({ page }) => {
	await page.goto('/drag-example');

	const item = page.locator('[data-testid="element-1"]');
	const areaA = page.locator('[data-testid="area-a"]');
	const areaB = page.locator('[data-testid="area-b"]');

	await expect(areaA).toContainText('Element 1');

	await item.dragTo(areaB);

	await expect(areaB).toContainText('Element 1');
	await expect(areaA).not.toContainText('Element 1');

	await areaB.getByText('Element 1').dragTo(areaA);

	await expect(areaA).toContainText('Element 1');
	await expect(areaB).not.toContainText('Element 1');
});

test('verifies drag visual feedback', async ({ page }) => {
	await page.goto('/drag-example');

	const source = page.getByText('Movable Element');
	const dropArea = page.locator('#target-zone');

	await source.hover();
	await page.mouse.down();

	const dropBox = await dropArea.boundingBox();
	await page.mouse.move(dropBox!.x + dropBox!.width / 2, dropBox!.y + dropBox!.height / 2);

	await expect(dropArea).toHaveClass(/drag-over|highlight/);

	await page.mouse.up();

	await expect(dropArea).not.toHaveClass(/drag-over|highlight/);
	await expect(dropArea).toContainText('Movable Element');
});
```

---

## File Drop Zone

```typescript
import { test, expect } from '@playwright/test';
import path from 'path';

test('uploads file via drop zone', async ({ page }) => {
	await page.goto('/upload');

	const dropZone = page.locator('[data-testid="file-drop-zone"]');

	await expect(dropZone).toContainText('Drag files here');

	const fileInput = page.locator('input[type="file"]');

	await fileInput.setInputFiles(path.resolve(__dirname, '../fixtures/report.pdf'));

	await expect(page.getByText('report.pdf')).toBeVisible();
	await expect(page.getByText(/\d+ KB/)).toBeVisible();
});

test('simulates drag-over visual feedback', async ({ page }) => {
	await page.goto('/upload');

	const dropZone = page.locator('[data-testid="file-drop-zone"]');

	await dropZone.dispatchEvent('dragenter', {
		dataTransfer: { types: ['Files'] }
	});

	await expect(dropZone).toHaveClass(/drag-active|drop-highlight/);
	await expect(dropZone).toContainText(/drop.*here|release.*upload/i);

	await dropZone.dispatchEvent('dragleave');

	await expect(dropZone).not.toHaveClass(/drag-active|drop-highlight/);
});

test('rejects invalid file types', async ({ page }) => {
	await page.goto('/upload');

	const fileInput = page.locator('input[type="file"]');

	await fileInput.setInputFiles({
		name: 'script.exe',
		mimeType: 'application/x-msdownload',
		buffer: Buffer.from('fake-content')
	});

	await expect(page.getByRole('alert')).toContainText(/not allowed|invalid file type/i);
	await expect(page.getByText('script.exe')).not.toBeVisible();
});
```

---

## Canvas Coordinate-Based Dragging

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

test('drags element to specific coordinates', async ({ page }) => {
	await page.goto('/design-tool');

	const canvas = page.locator('#editor-canvas');
	const shape = page.locator('[data-testid="shape-1"]');

	const canvasBox = await canvas.boundingBox();
	const targetX = canvasBox!.x + 300;
	const targetY = canvasBox!.y + 200;

	await shape.hover();
	await page.mouse.down();
	await page.mouse.move(targetX, targetY, { steps: 10 });
	await page.mouse.up();

	const newBox = await shape.boundingBox();
	expect(newBox!.x).toBeCloseTo(targetX - newBox!.width / 2, -1);
	expect(newBox!.y).toBeCloseTo(targetY - newBox!.height / 2, -1);
});

test('snaps element to grid', async ({ page }) => {
	await page.goto('/design-tool');

	const shape = page.locator('[data-testid="shape-1"]');
	const canvas = page.locator('#editor-canvas');

	const canvasBox = await canvas.boundingBox();

	await shape.hover();
	await page.mouse.down();
	await page.mouse.move(canvasBox!.x + 147, canvasBox!.y + 83, { steps: 10 });
	await page.mouse.up();

	const snappedBox = await shape.boundingBox();
	expect(snappedBox!.x % 20).toBeCloseTo(0, 0);
	expect(snappedBox!.y % 20).toBeCloseTo(0, 0);
});

test('constrains drag within boundaries', async ({ page }) => {
	await page.goto('/design-tool');

	const shape = page.locator('[data-testid="bounded-shape"]');
	const container = page.locator('#bounds-container');

	const containerBox = await container.boundingBox();

	await shape.hover();
	await page.mouse.down();
	await page.mouse.move(containerBox!.x + containerBox!.width + 500, containerBox!.y - 200, {
		steps: 10
	});
	await page.mouse.up();

	const shapeBox = await shape.boundingBox();

	expect(shapeBox!.x).toBeGreaterThanOrEqual(containerBox!.x);
	expect(shapeBox!.y).toBeGreaterThanOrEqual(containerBox!.y);
	expect(shapeBox!.x + shapeBox!.width).toBeLessThanOrEqual(containerBox!.x + containerBox!.width);
	expect(shapeBox!.y + shapeBox!.height).toBeLessThanOrEqual(containerBox!.y + containerBox!.height);
});

test('resizes element via handle', async ({ page }) => {
	await page.goto('/design-tool');

	const shape = page.locator('[data-testid="shape-1"]');
	await shape.click();

	const resizeHandle = shape.locator('.resize-handle-se');
	const handleBox = await resizeHandle.boundingBox();

	const initialBox = await shape.boundingBox();

	await resizeHandle.hover();
	await page.mouse.down();
	await page.mouse.move(handleBox!.x + 100, handleBox!.y + 80, { steps: 5 });
	await page.mouse.up();

	const newBox = await shape.boundingBox();
	expect(newBox!.width).toBeCloseTo(initialBox!.width + 100, -1);
	expect(newBox!.height).toBeCloseTo(initialBox!.height + 80, -1);
});
```

---

## Custom Drag Preview

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

test('shows custom drag preview', async ({ page }) => {
	await page.goto('/board');

	const card = page.locator('[data-testid="ticket-1"]');
	const targetCol = page.locator('[data-column="active"]');

	const cardBox = await card.boundingBox();
	const targetBox = await targetCol.boundingBox();

	await card.hover();
	await page.mouse.down();

	const midX = (cardBox!.x + targetBox!.x) / 2;
	const midY = (cardBox!.y + targetBox!.y) / 2;
	await page.mouse.move(midX, midY, { steps: 5 });

	await expect(page.locator('.drag-preview')).toBeVisible();
	await expect(card).toHaveClass(/dragging|placeholder/);

	await page.mouse.move(targetBox!.x + targetBox!.width / 2, targetBox!.y + targetBox!.height / 2, { steps: 5 });
	await page.mouse.up();

	await expect(page.locator('.drag-preview')).not.toBeVisible();
});

test('multi-select drag shows item count', async ({ page }) => {
	await page.goto('/board');

	await page.locator('[data-testid="ticket-1"]').click();
	await page.locator('[data-testid="ticket-2"]').click({ modifiers: ['Shift'] });
	await page.locator('[data-testid="ticket-3"]').click({ modifiers: ['Shift'] });

	const card = page.locator('[data-testid="ticket-1"]');
	const targetCol = page.locator('[data-column="complete"]');

	await card.hover();
	await page.mouse.down();

	const targetBox = await targetCol.boundingBox();
	await page.mouse.move(targetBox!.x + 50, targetBox!.y + 50, { steps: 5 });

	await expect(page.locator('.drag-preview')).toContainText('3 items');

	await page.mouse.up();

	await expect(targetCol.locator('[data-testid="ticket-1"]')).toBeVisible();
	await expect(targetCol.locator('[data-testid="ticket-2"]')).toBeVisible();
	await expect(targetCol.locator('[data-testid="ticket-3"]')).toBeVisible();
});
```

---

## Variations

### Keyboard-Based Reordering

```typescript
test('reorders using keyboard', async ({ page }) => {
	await page.goto('/priorities');

	const list = page.getByRole('list', { name: 'Priority list' });
	const priorityC = list.getByRole('listitem').filter({ hasText: 'Priority C' });

	await priorityC.focus();
	await page.keyboard.press('Space');

	await page.keyboard.press('ArrowUp');
	await page.keyboard.press('ArrowUp');

	await page.keyboard.press('Space');

	const items = await list.getByRole('listitem').allTextContents();
	expect(items[0]).toContain('Priority C');
});
```

### Cross-Frame Dragging

```typescript
test('drags between main page and iframe', async ({ page }) => {
	await page.goto('/composer');

	const sourceWidget = page.getByText('Component A');
	const iframe = page.frameLocator('#preview-frame');
	const iframeElement = page.locator('#preview-frame');

	const sourceBox = await sourceWidget.boundingBox();
	const iframeBox = await iframeElement.boundingBox();

	const targetX = iframeBox!.x + 100;
	const targetY = iframeBox!.y + 100;

	await sourceWidget.hover();
	await page.mouse.down();
	await page.mouse.move(targetX, targetY, { steps: 20 });
	await page.mouse.up();

	await expect(iframe.getByText('Component A')).toBeVisible();
});
```

### Touch-Based Drag on Mobile

```typescript
test('drags via touch events', async ({ page }) => {
	await page.goto('/priorities');

	const list = page.getByRole('list', { name: 'Priority list' });
	const source = list.getByRole('listitem').filter({ hasText: 'Priority C' });
	const target = list.getByRole('listitem').filter({ hasText: 'Priority A' });

	const sourceBox = await source.boundingBox();
	const targetBox = await target.boundingBox();

	await source.dispatchEvent('touchstart', {
		touches: [{ clientX: sourceBox!.x + 10, clientY: sourceBox!.y + 10 }]
	});

	for (let i = 1; i <= 5; i++) {
		const y = sourceBox!.y + (targetBox!.y - sourceBox!.y) * (i / 5);
		await source.dispatchEvent('touchmove', {
			touches: [{ clientX: sourceBox!.x + 10, clientY: y }]
		});
	}

	await source.dispatchEvent('touchend');

	const items = await list.getByRole('listitem').allTextContents();
	expect(items[0]).toContain('Priority C');
});
```

---

## Tips

1. **Start with `dragTo()`, fall back to manual mouse events**. Playwright's `dragTo()` handles most HTML5 drag-and-drop. Use `page.mouse.down()` / `move()` / `up()` only for custom libraries (react-beautiful-dnd, dnd-kit, SortableJS) that need specific event sequences.

2. **Add intermediate mouse steps for drag libraries**. Libraries like `react-beautiful-dnd` require multiple `mousemove` events. Use `{ steps: 10 }` or a manual loop — a single jump often fails silently.

3. **Assert final state, not just the drop event**. Verify DOM reflects the change — item order, column contents, position coordinates. Visual feedback during drag is secondary to the persisted state.

4. **Use `boundingBox()` for coordinate assertions**. For canvas editors or position-sensitive drops, capture bounding box after the operation and compare with `toBeCloseTo()` for tolerance.

5. **Test undo after drag operations**. If your app supports Ctrl+Z, verify the drag is reversible — this catches state management bugs.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall