@arcadialdev/arcality 2.2.0

package/.agents/skills/playwright-best-practices/testing-patterns/drag-drop.md

@@ -0,0 +1,576 @@
+# 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.