agentleFS
naomiaronaomiaro/waveform-playlist/.claude/skills/e2e-playwright/SKILL.md

e2e-playwright

Skill1.7k starsChanged yesterdayMITView on GitHub

Use when writing, changing, running or debugging a Playwright spec in e2e/, running pnpm test or npx playwright test, judging whether a red e2e run is a flake, starting or sharing a Docusaurus dev server for a test run, or proving a new e2e test against the old code.

2 other projects use a version of this.

Trending

Quiet this year.thin dataabout the whole repository

Dec 2025: 0 mentionsJan 2026: 0 mentionsFeb 2026: 0 mentionsMar 2026: 0 mentionsApr 2026: 0 mentionsMay 2026: 0 mentionsJun 2026: 0 mentionsJul 2026: 0 mentionsAug 2026: 0 mentionsSep 2026: 0 mentionsOct 2026: 0 mentionsNov 2026: 0 mentions
Dec 2025Jun 2026Nov 2026
Mentions a month of the naomiaro/waveform-playlist repository that our weekly crawl found: only 11 in all, so this is a hint, not a trend. There is no adoption data for this file yet.

Most recently taken up by

Who's talking about naomiaro/waveform-playlist

The biggest 5 of 11 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 11

Talked about on GitHub, Stack Overflow and Hacker News (11 times).

On GitHub · 8

3 more on GitHub

On Stack Overflow · 2

On Hacker News · 1

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Always rebuild (pnpm build) after switching branches before running tests — stale artifacts cause false failures

    line 19
  2. Very specific:

    Always await expect(locator).toBeVisible() before boundingBox() — returns null if element isn't laid out

    line 36
  3. Very specific:

    Use await expect(locator).toHaveCount(n) (auto-retrying) instead of expect(await locator.count()).toBe(n) (one-shot)

    line 37
  4. Very specific:

    Use Play/Pause/Stop buttons (not keyboard.press('Space')) for initial playback — AudioContext init is async and Space requires playlist …

    line 41
  5. Very specific:

    After clicking Play, wait for time to advance with retrying assertion: await expect(async () => { expect(await …

    line 42
  6. Distinctive:

    Escape in a test also reaches the Stop shortcut: when focus is on a plain button.

    line 51

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

E2E tests with Playwright

For measuring a page from an ad-hoc script or an MCP browser (render counts, audio taps, probe scripts) see the skill browser-probes.

Running the suite

  • Run tests: pnpm test, pnpm test:ui (interactive), pnpm test:headed (visible browser). The suite's only project is Chromium. Playwright's Firefox needs @playwright/test >= 1.65 on this machine (macOS 27): the Firefox builds shipped with 1.60 fail to launch with sandbox_extension_issue_file_to_process … Operation not permitted and a timeout — that is Firefox's own content sandbox, NOT Claude Code's Bash sandbox (do not add sandbox settings for it; enabling the Bash sandbox blocks local ports, browser launches and gh). One-off cross-browser run: a temporary config that spreads playwright.config.ts and replaces projects with devices['Desktop Firefox'], npx playwright test --config <tmp>. On Firefox 159 the suite was 183/184 (2026-11-10): multi-clip.spec.ts "pressing 0 rewinds to start" fails ~10/10 under the runner — Play is clicked and isPlaying stays false — equally with the provider from before #676, and 24/24 fresh sequential loads outside the runner play fine; cause not found. Playwright's WebKit (26.4 and 27.2) cannot create dawcore's blob-URL peak worker (WebKitBlobResource error 1), so <daw-editor> pages load no tracks there; whether real Safari is affected is unknown. The test script is root-only — use pnpm -w run test from package directories.
  • Config: playwright.config.ts - uses BASE_PATH and PORT env vars
  • Location: e2e/ directory
  • The Playwright suite is not part of CI, and there is one way to run it (pnpm test, everything, about a minute plus the builds; 258 tests as of 2026-11-12, after #685 part 2). #779 tracks tags and scripts for running it by area. Until then the full run on the PR's head commit is the rule.
  • pnpm test starts everything it needs and should be all green (231 tests as of 2026-11-11; count with npx playwright test --list; all green since the 2026-11-10 flake sweep). playwright.config.ts starts BOTH dev servers (Docusaurus, and the dawcore-native Vite example on port 5273 for dawcore-spectrogram.spec.ts — no manual server any more) and e2e/global-setup.ts visits every example route once so no test pays a route's first lazy compile inside its own 30 s readiness timeout. A red e2e run is now a signal: don't wave it off as flake without measuring. To measure a suspected flake, compare failure RATES, not single runs — start the site yourself (cd website && pnpm exec docusaurus start --port 3077 --no-open), then PORT=3077 npx playwright test <spec> -g "<name>" --repeat-each=10 on the branch and on main (the config reuses a running server; one main run is not a baseline). A "flaky playback-start test" was a real bug too (#675): waveform-data.spec.ts's play tests failed ~1 in 10 because Play landed during an engine rebuild — see "Engine Rebuilds vs Playback" in packages/browser/CLAUDE.md. Standalone stress scripts did NOT reproduce it; a temporary spec run under the real runner (--repeat-each on the whole spec file, console + data-playlist-state transitions logged on failure) did. When a script can't reproduce a runner failure, instrument inside the runner. For a failure that shows once in a few hundred runs: send the runner's output to a file (a tail of it loses the one message you need), then read test-results/<test>-repeatN/error-context.md (the failing assertion) and test-failed-1.png (the page at that moment; a dead meter and a blank clip in that screenshot pointed at the microphone, not at the code under test). Temporary console.log lines in the spec appear in the runner's output; check that the condition that triggers them can actually be true before spending a 200-run batch on it (#695: a probe that counted the peak marker as a lit segment never fired). A "flaky readiness timeout" can be a real bug: the effects page's intermittent [data-playlist-state="ready"] timeouts were Tone effects built on the wrong AudioContext ("cannot connect to an AudioNode belonging to a different AudioContext" in the console, playlist stuck in loading) — found by loading the page 40× concurrently from a script and reading the console, which took minutes after months of the tests being labelled flaky. Selector lessons from the same sweep: never address a control by position (input[type=range]…first() matched a different slider depending on what had mounted — give it an accessible name and use getByRole), and never read computed style one-shot (toHaveCSS retries).
  • A fresh worktree fails 18 MediaElement e2e tests (the page shows "WaveformData.create(): This waveform data version not supported"): /examples/media-element loads its audio and .dat from /waveform-playlist/storybook/media/…, which exists only after pnpm --filter website build:storybook writes the git-ignored website/static/storybook/. Build it, or ln -s <main checkout>/website/static/storybook website/static/storybook for the run and rm it afterwards.
  • npx playwright test <spec> without PORT starts its own server on 3000 and crashes a Docusaurus server already running on another port (shared rspack cache). With my own server up, always PORT=3077 npx playwright test … / PORT=3077 pnpm test.
  • Always rebuild (pnpm build) after switching branches before running tests — stale artifacts cause false failures

Dev servers

  • A dev server already on port 3000 makes pnpm test lie, and pnpm build breaks that server. The Playwright config reuses whatever is listening on 3000, and the maintainer often has their own Docusaurus server running while trying a branch. pnpm build rewrites packages/*/dist underneath it, leaving a "Can't resolve '@dawcore/components'" compile overlay (<iframe id="webpack-dev-server-client-overlay"> "intercepts pointer events" in the Playwright log) and dozens of false failures. Before either command: lsof -nP -iTCP:3000 -sTCP:LISTEN. If something is there and you did not start it, do not kill it and do not build: cd website && pnpm exec docusaurus start --port 3077 --no-open, then PORT=3077 pnpm test, and tell them their server needs a restart if a build already ran. A website dev server also reads dawcore's dist, so after changing dawcore's imports of core, rebuild before trusting it ("X is not exported from '@waveform-playlist/core'").
  • A branch switch breaks the maintainer's dev server as surely as a build. Once a PR has been announced as ready to try, assume their server is running in this checkout: check the port before git checkout as well as before a build, as a command of its own (not chained in front of the thing it guards). For a follow-up fix to what they are trying, stack the new branch on the branch they are on, so the page under test stays in the working tree (#747 was branched from main first, which removed the demo page they had open).
  • Two Docusaurus dev servers share one rspack cache, so do not swap source files under the second one. With the maintainer's server on 3000 and mine on 3077, git checkout main -- <files> for an A/B baseline crashed mine on the recompile (should have bucket pack metas, SIGABRT), and their server was answering 404 for example routes afterwards (cause not established; a ui-components build had also run). For a baseline: check the baseline files out FIRST, start the 3077 server, measure, restore the files (a recompile after restoring survived). Tell the maintainer their server may need a restart.

Selectors and pages

  • Key Selectors: [data-clip-id], [data-boundary-edge], [data-clip-container], [data-scroll-container]
  • MediaElement pages have [data-playlist-state] since #685 part 2, always "ready": it says the view is mounted, not that the media element has loaded (for that read useMediaElementTrack().isReady or use the provider's onReady; the Play button is enabled before the media has loaded); older specs wait for [data-scroll-container] canvas, which still works. The clip there is itself an [aria-roledescription="draggable"], so annotation handle counts are off by one: wait for toHaveCount(1) (the clip; dnd-kit adds the attribute late, so never a one-shot count()) before enabling Editable, then expect 1 + 2 per annotation. probes/select744.cjs is select740.cjs with a READY env var for the wait selector.
  • Clip drag/trim live on /examples/multi-clip (<WaveformEditor />); /examples/stem-tracks renders NO clip headers ([data-clip-id] never appears) — it's the track-reorder page. Don't wait on a header selector there.
  • The MediaElement player's <audio> element is not in the document (new Audio()), so document.querySelectorAll('audio') finds nothing. To assert the playback rate in e2e, read the AudioPosition text and performance.now() together inside one page.evaluate, wait a second in the page, read again and compare the ratio (playbackSpeed in e2e/media-element.spec.ts).

Assertions that do not flake

  • Always await expect(locator).toBeVisible() before boundingBox() — returns null if element isn't laid out
  • Use await expect(locator).toHaveCount(n) (auto-retrying) instead of expect(await locator.count()).toBe(n) (one-shot)
  • Wrap post-interaction state checks with await expect(async () => { ... }).toPass({ timeout: 5000 }) for timing tolerance
  • Wrap boundingBox() in await expect(async () => { box = await el.boundingBox(); expect(box).toBeTruthy(); }).toPass() — returns null before layout completes
  • Wrap one-shot evaluate() for computed styles in .toPass() — styles may not be applied on first query
  • Use Play/Pause/Stop buttons (not keyboard.press('Space')) for initial playback — AudioContext init is async and Space requires playlist focus
  • After clicking Play, wait for time to advance with retrying assertion: await expect(async () => { expect(await timeDisplay.textContent()).not.toBe('00:00:00.000'); }).toPass({ timeout: 10000 })
  • A count used as the expected value is a one-shot read too. const total = await rows.count(); await expect(audioRows).toHaveCount(total) on the multi-clip page read 6 while the seventh row was being added and failed 1 full run in 6 (#758, fixed in #760). Put the count and the comparison inside one expect(async () => { … }).toPass().
  • A retrying e2e assertion can pass before the thing under test has happened. The spectrogram canvas was the right size from React's render; the worker resized it a moment later, and toPass() on the size passed with the fix removed (#689). When the code under test acts asynchronously after the render, assert again after it has had time, and break the guarded line for e2e tests too.
  • A page.route glob that matches nothing fails silently. On #782 a test aborted **/*.mp3 while the page plays .opus; the request went through and the test said nothing about the error path. Take the URL from the page's network requests, and count the handler's calls (expect(hits).toBeGreaterThan(0)).
  • page.mouse.click(x, y) does not scroll. The test viewport is 1280x720; a row below the fold is never hit and nothing errors. await locator.scrollIntoViewIfNeeded() before boundingBox(). When a raw click "does nothing", print document.elementsFromPoint(x, y) first: on /examples/mir-spectrogram the tracks are only about 95 px wide, and a click at x + 300 landed beside them.
  • Measure geometry after clicking Play. The click can scroll the page (Playwright scrolls the button into view), so a boundingBox() taken before it is stale: on #793 a probe pressed beside the track and reported "a press during playback does nothing", the opposite of what happens.
  • An assertion that playback "moves on" inside a range needs a range that outlasts a retry. With a 1.5 s range the passing window closes when the range ends and the cursor returns to its start; toPass cannot recover after that. Use about 3 s. Without such an assertion, "the release plays the range" also passes when the release merely stops playback at the range's start.
  • A test for a rule about scrolling needs a state where the view scrolls. /examples/multi-clip barely scrolls at its default zoom (the timeline is about as wide as the container); two clicks on Zoom In give 187.5 px per second and the view follows the playhead within a few seconds. Wait for scrollLeft to grow before pressing, and compare the playhead's content x with scrollLeft + (pressX - frame.x) taken at the press.
  • .check() on a radio or checkbox whose change handler unmounts it times out (the track menu closes when a render mode is chosen, so Playwright cannot confirm the checked state). Use .click(), then prove the result another way (reopen the menu and toBeChecked()).
  • Escape in a test also reaches the Stop shortcut when focus is on a plain button. Close a menu with its own button unless Escape is what the test is about.
  • A probe or test that finds a control by a loose accessible name can press another control. probes/split768.cjs matched name: 'Volume' and pressed "Master Volume": the "track volume" baselines of two sessions (16 and 33) were the master slider (real: 32 and 63; probes/track687.cjs). On #687 a new "Remove track" title made getByRole('button', { name: 'Remove' }).last() in effects.spec.ts remove a track. Use exact: true.

Pointer and input

  • A drag that ends in the bottom or top 20% of the viewport makes dnd-kit auto-scroll the page. On #812 a page that became 31 px taller moved a track-reorder drop from y=566 to y=597 (viewport 720, band from 576): the page scrolled about 108 px mid-drag, the track landed two slots down, and the test passed 5 of 20. Scroll the drag source to mid-viewport first (scrollIntoView({ block: 'center' })), then read positions. To tell a regression from a flake, run the one test with --repeat-each=20 on the head and again with the previous commit's pages (git checkout <sha> -- website/src under my own server, then git restore --source=HEAD --staged --worktree -- website): 5 of 20 against 20 of 20 named the commit. Commit before such a swap: the restore takes uncommitted edits with it.
  • Mouse drags in Playwright: page.mouse reports buttons: 1 while a button is down, and a new MouseEvent('mousemove') in a unit test reports buttons: 0 unless told otherwise; code that checks event.buttons needs { buttons: 1 } in jsdom tests. A page.mouse.move(x, y, { steps }) that leaves an element diagonally keeps changing whatever the drag controls on the way out; move straight out along the other axis when the assertion is about the dragged range. Holding the button over page text selects it unless the page prevents that; window.getSelection().toString() after the drag shows it. The mobile specs drive the mouse, so nothing in the suite sends real touch events.
  • Fractional pointer positions reach dnd-kit: page.mouse.move(x + 0.3, y) arrives as a fractional pointer coordinate, so a drag can end between pixels. Use that when a bug depends on a sub-pixel remainder (#747: a gap under 10 ms between two annotation edges needs a 0.3 px offset at 23 ms per pixel; whole-pixel drags always landed exactly and could not reproduce what a real mouse did about half the time). Read the times the UI shows (the annotation list rows), not box positions, to see millisecond differences.
  • Synthetic dispatchEvent(new PointerEvent(...)) cannot drive PointerHandler interactions — setPointerCapture throws NotFoundError for fabricated pointerIds. Use real input (page.mouse.click/move/wheel) when verifying seek/drag/wheel behavior in a live browser.
  • Synthetic .click() on a dawcore web-component HOST (daw-stop-button, etc.) silently no-ops — the @click is on the inner <button> in shadow DOM, and a host-targeted click doesn't propagate in. Click el.shadowRoot.querySelector('button') (or use real pointer input). It looks like a broken control but isn't — a host .click() only works when the page also adds a host-level listener (as the record demo does for its record button).
  • Synthetic .click() on a Play button can wedge isPlaying with no audio — the React handler runs but the untrusted-gesture media.play() is rejected by autoplay policy, so the UI shows playing (Play disabled) while nothing plays. Use real input (page.locator(...).click()) for playback in MCP-driven browsers.
  • Verifying a drop animation is disabled: sample document.getAnimations() immediately after page.mouse.up() — dnd-kit's Feedback drop animation is a Web Animation on the dragged element, so an empty list is rAF-independent proof of dropAnimation: null; a settled final position is NOT (the element animates back and then jumps).
  • Firefox innerText excludes non-selected <option> text (Chromium includes it) — assert select.options structurally, never via body-text probes, in cross-browser checks.

Recording

  • Recording flows are fully testable headless with a synthetic mic — Playwright MCP browser_run_code_unsafe: context.grantPermissions(['microphone'], { origin }) (per-origin — re-grant for each port) + context.addInitScript replacing navigator.mediaDevices.getUserMedia with an oscillator → createMediaStreamDestination() stream (wrap the track's getSettings to report channelCount/sampleRate; also stub enumerateDevices). Launch with --autoplay-policy=no-user-gesture-required (test.use({ launchOptions: { args: [...] } }) in a spec, chromium.launch({ args }) in a script): the oscillator's own AudioContext is created when the page asks for the microphone on load, before any click, and without the flag it stays suspended in about 1 run in 30, so the "microphone" is silent (dead input meter, blank recorded clip). e2e/recording.spec.ts failed 7 runs in 200 without it and 0 in 300 with it; when a synthetic-mic test sees no signal, check the fake context's state before suspecting the library. Headless Chromium reports visibilityState: 'visible' with full-rate rAF — sidesteps the hidden-tab trap entirely, and the whole record→overdub→finalize flow runs deterministically. When a claude-in-chrome tab won't foreground (display asleep/locked — AppleScript activate + window reorder don't wake rAF), switch to headless Playwright instead of fighting window management. The dawcore record demo needs its #mic-btn clicked first (editor.recordingStream is set there, not by the record button). Its record button also AUTO-CREATES a new track when nothing is selected — to test punch-in-on-top, select the content track first (editor._setSelectedTrackId(id)), or you'll record onto a fresh empty track and measure the wrong one.

Proving a new test

  • See a new e2e test fail against the old code before trusting it. With no dev server running: git checkout <base> -- <the example or source file>, run the one test (npx playwright test <spec> -g "<name>"; the config starts and stops its own server, so no file changes under a live one), read WHY it failed, then git checkout HEAD -- <file> and run it again. A unit test gets the same check by breaking the line it guards and watching it fail.
  • For a change that spans packages, the old code is git checkout main -- packages (the new specs under e2e/ stay), then delete the files the branch ADDED under packages/ (git diff --name-only --diff-filter=A main HEAD -- packages; left in place they fail pnpm build's typecheck against the old types), pnpm build, run the new tests. Restore with git restore --source=HEAD --staged --worktree -- packages (it also removes the files the branch deleted, which the checkout brought back), confirm git status --short is empty, and build again. Commit first: all of this needs a clean tree to come back to.
  • Old-code check for a new e2e test (#762): after git checkout main -- <source file>, run pnpm --filter <pkg> build before the spec. Without it the first run did not show an attribute added in another file of the same package, and both tests failed for the wrong reason. Keep a control test that passes on the old code, so a failure of the real test means the bug and not the setup.
  • An e2e test that finds its elements through a new attribute fails on the old code for the attribute, not for the behaviour in its title. Say which of the two the old-code run proved.
  • Before changing how an interaction computes its result, find the e2e test and the PR that set the current behaviour. On #749 the annotation edge drag was changed to compute each move from the drag-start state (dawcore does it that way). That removed what #747 had established and the maintainer had tried by hand: with Link endpoints on, an edge dragged into a separated neighbour carries it along. Only e2e/media-element-annotations.spec.ts caught it; every unit test passed. The React hook and dawcore's handler differ here on purpose.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.