E2e Test Create

Read React component source to understand DOM structure. No browser needed — source code has everything.

1. Find relevant components: Glob and grep frontend/src/metabase/ for the feature area.
2. Extract selectors: Grep for data-testid in relevant components.
3. Note visible text: Read component JSX for button labels, headings, placeholders.
4. Note aria attributes: Grep for aria-label in relevant components.
5. Understand user flows: Read event handlers (onClick, onSubmit, onChange) to understand interactions.
6. Find API calls: Grep for Api.use, fetch, useQuery, endpoint definitions to identify API calls to intercept.
7. Cross-reference with existing specs: Find specs in the same area and reuse their proven selectors and cy.intercept patterns.

Phase 2 — Start Backend

Use MB_EDITION=oss by default. Only use MB_EDITION=ee when the user explicitly asks to write an enterprise test.

Start the backend using run_in_background: true (NOT &). bin/e2e-backend automatically detects if a backend is already running and reuses it.

MB_EDITION=oss bin/e2e-backend

Do NOT manually generate snapshots by running unrelated test specs. The bun test-cypress runner has GENERATE_SNAPSHOTS: true by default and automatically generates snapshots before running any spec. When running tests in Phase 4 via the /e2e-test skill, snapshots will be generated on the first run if they don't already exist.

Restore clean test data:

curl -sf -X POST http://localhost:4000/api/testing/restore/default

Phase 3 — Generate Cypress Spec

File location & naming

Place specs in e2e/test/scenarios/<area>/ mirroring the URL structure. Name: <feature>.cy.spec.js (NOT .cy.spec.ts).

Metabase conventions (mandatory)

• Helpers via cy.H: All helpers are accessed via const { H } = cy; — NOT via direct imports from e2e/support/helpers.

const { H } = cy;

describe("feature name", () => {
  beforeEach(() => {
    H.restore();
    cy.signInAsAdmin();
  });
});

• Sample Database schema (table/field definitions): Import from cypress_sample_database.

import { ORDERS, ORDERS_ID, PRODUCTS } from "e2e/support/cypress_sample_database";

• Instance data (dashboard IDs, user IDs, etc.): Import from cypress_sample_instance_data.

import { ORDERS_DASHBOARD_ID } from "e2e/support/cypress_sample_instance_data";

• Selectors (priority order):

  1. cy.findByText() / cy.findByLabelText() / cy.findByRole() — from @testing-library/cypress
  2. cy.findByTestId() — for data-testid attributes
  3. cy.get("[data-testid='...']") — fallback
  4. NEVER use positional selectors, CSS class names, or XPaths.

• Navigation helpers: Use existing helpers like H.openOrdersTable(), H.openNativeEditor(), H.visitDashboard(id), H.visitQuestion(id) instead of raw cy.visit() chains. Grep e2e/support/helpers/ to discover what's available for your area.

• API setup over UI setup: Use cy.request() or existing API helpers to set up state. Only use the UI for the flow you're actually testing.

• Assertions: Assert on visible text, URL, aria state — not DOM structure.

• Waits: Never use cy.wait(ms). Use cy.intercept() + cy.wait("@alias") for API calls, or cy.findByText().should("be.visible") for DOM readiness.

• Isolation: Each it() block must be independently runnable. Don't depend on state from a previous it().

Spec structure template

const { H } = cy;
import { ORDERS_DASHBOARD_ID } from "e2e/support/cypress_sample_instance_data";
import { ORDERS, ORDERS_ID } from "e2e/support/cypress_sample_database";

describe("area > sub-area > feature (#issue-number)", () => {
  beforeEach(() => {
    H.restore();
    cy.signInAsAdmin();
  });

  it("should do the primary happy-path thing", () => {
    // test
  });

  it("should handle the edge case", () => {
    // test
  });
});

Intercepts

When you identified API calls during code analysis, stub or wait on them:

cy.intercept("POST", "/api/dataset").as("dataset");
// ... trigger action ...
cy.wait("@dataset");

Phase 4 — Validate

After generating specs:

1. Check that all imported helpers exist (Grep e2e/support/helpers/).
2. You MUST use the /e2e-test skill to run tests — do NOT run bun test-cypress directly. The /e2e-test skill handles edition selection, snapshot management, and correct env vars. /e2e-test GREP="should do the thing" --spec e2e/test/scenarios/<path> If you created multiple it() blocks, run each one individually to isolate failures.

Phase 5 — Fix Failures (up to 2 attempts)

When a test fails, try to fix it from Cypress output first:

1. Read the failure screenshot (path printed under (Screenshots)).
2. Read the error message and code frame from the console output.
3. Fix the test and re-run (back to Phase 4, step 2).

If you cannot diagnose the issue after 2 attempts, proceed to Phase 6.

Phase 6 — Playwright Fallback

Only reach this phase after 2 failed fix attempts from Phase 5. The backend is already running.

Restore clean test data:

curl -sf -X POST http://localhost:4000/api/testing/restore/default

Bypass CSP headers before navigating (Metabase serves strict CSP that blocks dev server scripts). Use browser_run_code to set this up:

async (page) => {
  // Strip CSP headers so the page loads (mirrors Cypress chromeWebSecurity: false)
  await page.context().route('**/*', async (route) => {
    const response = await route.fetch();
    const headers = { ...response.headers() };
    delete headers['content-security-policy'];
    delete headers['content-security-policy-report-only'];
    await route.fulfill({ response, headers });
  });

  // Sign in via API
  const response = await page.request.post('http://localhost:4000/api/session', {
    data: { username: '[email protected]', password: '12341234' }
  });
  const session = await response.json();
  await page.context().addCookies([{
    name: 'metabase.DEVICE',
    value: session.id,
    domain: 'localhost',
    path: '/'
  }]);

  await page.goto('http://localhost:4000');
  await page.waitForLoadState('networkidle');
  return 'signed in';
}

Maintain an observation log incrementally. After EVERY significant Playwright interaction, IMMEDIATELY append what you observed to the scratch file BEFORE performing the next interaction:

cat >> /tmp/e2e-observations.md << 'OBSERVATION'
## [Page/Flow name]
- URL: /question/notebook#...
- Clicked: "Box plot" button → visible text "Box plot", role: radio
- Selectors: data-testid="viz-type-button", findByText("Box plot")
- API call: POST /api/dataset (triggered on viz change)
- Key state: after selecting viz type, summary sidebar shows metric picker
OBSERVATION

For each page/flow:

• Take an accessibility snapshot (browser_snapshot).
• Click through interactive elements, fill forms, trigger modals.
• Append to the observation log immediately after each step: URLs, visible text, aria labels, data-testid attrs, API calls.
• Screenshot key states.

After exploration:

1. Read back your observation log: cat /tmp/e2e-observations.md
2. Fix the test using observed selectors and behavior.
3. Re-run the test (back to Phase 4).
4. Clean up: rm -f /tmp/e2e-observations.md

Phase 7 — Cleanup

After all tests pass (or after giving up on fixing failures), always kill the backend on port 4000:

lsof -ti:4000 | xargs kill 2>/dev/null || true

Do NOT use broad pkill patterns — there may be other Metabase instances on different ports. The backend process started in Phase 2 will NOT be killed automatically when the Claude session ends. Leaving it running wastes resources and can interfere with future sessions. Always clean up.

What NOT to do

• Do NOT use Playwright as the first step — always analyze source code first.
• Do NOT kill the backend between phases — it stays running throughout.
• Do NOT invent selectors you didn't find in source code or observe in the browser.
• Do NOT hardcode database IDs — import from cypress_sample_database or cypress_sample_instance_data.
• Do NOT use cy.wait(1000) or any numeric wait.
• Do NOT create setup flows through the UI when an API helper exists.
• Do NOT put tests in cypress/e2e/ — Metabase uses e2e/test/scenarios/.
• Do NOT import helpers directly from e2e/support/helpers — use const { H } = cy;.