the-controller-general-e2e-eval

General E2E Eval — User Story Validation

When to Use

You've made a UI change in any web project and need to prove it works from the user's perspective — not "it compiles" or "the DOM element exists," but "the user can do the thing and see the result."

Use this skill for projects that don't have a custom eval script. If the project has e2e/eval.sh or similar, use the project-specific eval skill instead.

Hard Rules

These are non-negotiable. Every test must follow all of them.

1. User story first, always

Before writing a single line of test code, state the user story:

• Actor: Who is performing the action (e.g., "a logged-in user on the settings page")
• Action: What they physically do (e.g., "clicks 'Save' after changing their display name")
• Outcome: What they expect to see (e.g., "a success toast appears and the new name is shown in the header")

The test's final assertion must verify the outcome. If the outcome doesn't happen, the test fails. No exceptions.

2. No silent passes

BANNED — the if (visible) escape hatch:

// NEVER DO THIS — silently passes when the feature is broken
const visible = await foo.isVisible().catch(() => false);
if (visible) {
  await expect(foo).toHaveText("expected");
}

REQUIRED — unconditional assertion with a timeout:

// DO THIS — fails loudly when the feature is broken
await expect(foo).toBeVisible({ timeout: 10_000 });
await expect(foo).toHaveText("expected");

If the element should be there, assert it. If it might legitimately not be there, that's a different test or a precondition you need to set up.

3. No mocking the interface

• No page.evaluate() to set store state when a real interaction exists. If the user clicks a button to open a modal, the test clicks the button.
• No synthetic dispatchEvent(new KeyboardEvent(...)) — use page.keyboard.press().
• No stubbing API responses — the test runs against a real dev server.