test(e2e): port authored_hints to Playwright (pages/components layout)

[stephenliang]

Ports the first Cucumber UI test to Playwright — teacher_tools/authored_hints.feature → frontend/packages/e2e-tests — and establishes the suite layout future ports will follow.

What's new

The test. authored-hints.spec.ts covers the full scenario: view three hints via the lightbulb and "Yes" prompt, count badge decrements then disappears, hint image loads, and clicking the exhausted lightbulb does nothing. The Cucumber original is tagged @playwright.

The layout. Specs live in per-area directories; reusable code is centralized:

tests/
├── activities/authored-hints.spec.ts   # specs, by product area
├── pages/legacy-blockly-lab.ts         # page objects
├── components/authored-hints.ts        # feature objects composed into pages
└── shared/                             # per-domain helpers
    ├── nav.ts                          # navigation; rejects absolute URLs so tests can't bypass TARGET_URL
    └── routes.ts                       # labLevelUrl({lesson, level, ...}) route builder

Composition over inheritance. Authored hints are a feature of the shared legacy CSF instructions UI (apps/src/templates/instructions), not a page — AuthoredHintsComponent is composed into the LegacyBlocklyLab page object, so specs read as lab.hints.viewNext() / lab.hints.assertCount(2).

Net benefits vs the Cucumber implementation

• Selectors exercise the accessibility tree. The Cucumber steps drive jQuery CSS (#lightbulb, button:contains(Yes)); the port uses getByRole('button', {name: 'lightbulb'}) and getByRole('button', {name: 'Yes', exact: true}), verified against the live DOM. The test now fails if these controls lose their button role or accessible name — a regression Cucumber couldn't see.
• The image assertion is no longer vacuous. Cucumber's $('.csf-top-instructions img').prop('complete') reads the first matching <img>, which can be the Immersive Reader icon rather than the hint content. The port scopes to the hint image and also checks naturalWidth > 0 (decoded, not merely complete-with-error).
• Auto-retrying assertions replace jQuery polling. Every wait is a web-first expect with one consistent timeout profile (expect.timeout); no execute_script polling loops, and no dependency on the app's jQuery global from inside tests.
• Faster, more debuggable failures. The scenario runs in ~3–9s per browser directly against test-studio (no Selenium/Sauce hop), and CI failures come with Playwright traces, screenshots, and video.
• Verified on three engines. Green 5× each on chromium, firefox, and webkit; Firefox and WebKit are opt-in CI lanes via --project.
• Typed, lintable test code. TypeScript page/component objects under yarn typecheck + eslint, vs regex-matched Ruby step definitions composing selector strings.

Links

• Jira: n/a
• Porting workflow: feat(e2e): agentic Cucumber→Playwright porting workflow #72977
• PoC reference branch: stephen/playwright

Testing story

• 5× repeat per browser (chromium, firefox, webkit) against test-studio.code.org: 15/15 green.
• yarn typecheck, yarn lint, and the pre-commit hook all pass.

Deployment notes

The @playwright tag is not yet honored by the UI test runner — the scenario runs in both suites until skip_tag('@playwright') is added to dashboard/test/ui/runner.rb (intentional follow-up).

🤖 Generated with Claude Code