musicthing-playwright

name	musicthing-playwright
description	Use when developing or verifying Musicthing browser UI with Playwright as an agent feedback loop, including clicking through local React screens, visible-change screenshots, debug screenshots, console/network evidence, local-first storage checks, import/export round trips, responsive checks, or reproducing browser-only bugs.

Musicthing Playwright

Use Playwright as the agent's browser feedback loop for rendered Musicthing UI behavior. The goal is to click through the app, observe what changed, catch obvious browser issues, and capture evidence while developing. Structured e2e test suites can come later.

What To Carry Forward

Adapt these practices from the user's work tooling, without copying its project structure:

• Verify rendered behavior in a real browser with Playwright-driven clicking.
• Capture screenshots for every task with visible changes.
• Capture debug screenshots when the UI is surprising, broken, or hard to reason about from code alone.
• Collect console and network evidence for behavioral bugs.
• Use stable locators and scoped selectors instead of broad exact-text matches.
• Treat browser launch/tooling failures separately from app failures.
• Avoid printing broad environments, .env*, storage dumps, credentials, keys, or other secret-bearing diagnostics.

Musicthing Defaults

• App stack: React under code/.
• Node policy: if Node is missing and setup work requires it, install Node with nvm.
• Storage model: IndexedDB for library data; localStorage only for small preferences.
• Core MVP flows: song CRUD, ChordPro chart editing, setlist editing, full-library export, full-library import.
• Task artifacts: each task should have a folder under docs/tasks/<task-id>-<slug>/.
• Evidence artifacts: save task screenshots, debug screenshots, sample exports, and notes under that task folder's outputs/.

Workflow

1. Identify the task folder in docs/tasks/. If none exists, create one with prd.md, plan.md, and outputs/.
2. Inspect code/README.md, package.json, playwright.config.*, and existing test commands before adding tools.
3. If the React app is not scaffolded yet, record Playwright expectations in the task PRD or plan instead of inventing an app structure.
4. Start the local dev server before browser verification. Use the app's documented command and keep the server running until checks finish.
5. Use Playwright to click through the changed UI like a user and gather feedback.
6. Run desktop and mobile-sized checks for user-facing UI changes.
7. For any visible change, save at least one screenshot in the task outputs/ folder before finishing.
8. Report the exact command, URL, viewport, screenshot path if any, and whether console/network errors appeared.

E2E Boundary

Do not turn every browser check into a formal e2e test yet. For now, Playwright is primarily a development feedback tool for the agent.

When structured e2e tests are introduced later, prefer:

• code/playwright.config.ts
• code/tests/e2e/*.spec.ts
• code/test-results/ ignored by git
• code/playwright-report/ ignored by git

Keep Playwright test data small and local. Do not require cloud accounts, sync services, or real external APIs for MVP browser checks.

Local-First Checks

For Musicthing features, use Playwright to check at least one relevant category:

• Persistence: create data, reload, confirm it remains.
• Import/export: export a library, clear or use a fresh context, import it, confirm songs and setlists return.
• Storage boundaries: verify library data uses IndexedDB or the chosen durable browser store; keep localStorage limited to preferences.
• Offline posture: avoid tests that require network after the app bundle is loaded unless the feature explicitly needs it.
• Portability: validate exported files include a format version and ChordPro chart text plus Musicthing metadata.

Locator And Evidence Rules

• Prefer accessible locators: getByRole, getByLabel, getByPlaceholder, and scoped locator(...).filter(...).
• Avoid brittle selectors tied to generated class names.
• Avoid broad exact-text locators when the same label may appear in a nav item, card, modal, and description.
• Add page.on('console', ...) and failed response capture when reproducing defects.
• Use traces for hard-to-reproduce browser behavior, but do not commit trace archives unless requested.
• Store screenshots and debug screenshots in the task outputs/ folder with descriptive names.

Minimal Example

Use this shape for a temporary smoke script or later formal test once the app exists:

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

test('loads the local-first library shell', async ({ page }) => {
  const consoleErrors: string[] = [];
  page.on('console', message => {
    if (message.type() === 'error') consoleErrors.push(message.text());
  });

  await page.goto('/');
  await expect(page.getByRole('heading', { name: /musicthing/i })).toBeVisible();
  expect(consoleErrors).toEqual([]);
});

For import/export tests, use a fresh browser context or clear app storage between export and import steps so the test proves portability rather than only in-memory state.