the-controller-e2e-eval

E2E Eval — User Story Validation

When to Use

You've made a UI change 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."

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 user in Architecture mode")
• Action: What they physically do (e.g., "presses r")
• Outcome: What they expect to see (e.g., "an architecture diagram renders in the diagram pane")

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 presses Space to open the workspace picker, the test presses Space.
• No synthetic dispatchEvent(new KeyboardEvent(...)) — use page.keyboard.press().
• No stubbing API responses — the test runs against real servers via eval.sh.

The only acceptable use of page.evaluate() is to read state for assertions (e.g., checking a computed style), never to write state that bypasses the UI.

4. Assert outcomes, not implementation

WRONG — asserting CSS values and class names: