feat(mcp): tell the agent to read the writing-tests guide before it writes a test

Merged
KA
6d ago
+27-9

An agent driving the app through e2e mcp would start writing a test without reading the writing guide. Before this change, the server mentioned the guide resources only at the end of its instructions, and many clients drop instructions or never read resources.

  • One sentence, READ_WRITING_GUIDE (packages/e2e/src/mcp/session.ts), now appears in two places: the server instructions, before "Write the test…", and at the end of every open_session summary, above the first observation, test runs included.

  • It names the resource and a shell fallback, for clients that can't read MCP resources:

    Before you write or edit a test, read the writing-tests guide: the resource e2e://guide/writing-tests, or npx e2e guide writing-tests in a shell.
    
  • Updated to match: workflow step 1 in skills/e2e/references/mcp.md (plus the plugin copy) and open_session in docs/reference/mcp.mdx. Includes a patch changeset for e2e.

Linear: ENG-1269

Verified

Ran it locally: yes

  • Surface: the built e2e mcp (packages/e2e/dist/cli/bin.js), driven by an MCP SDK client. The testbed's port was held by another checkout's app, so I opened the session in engine mode from an empty directory against that running app.
  • The instructions and the open_session result both carry the line, and the resource it names resolves:
--- instructions (last paragraph) ---
Before you write or edit a test, read the writing-tests guide: the resource e2e://guide/writing-tests, or npx e2e guide writing-tests in a shell. Write the test (tests/*.e2e.ts) while you walk the flow, ...
--- open_session result, before the screen ---
Session 01a1ca21-… open on target "web" (platform web, engine web 0.15.5), headless; no config file: ...
App: http://127.0.0.1:4271/.
...
Node ids ("n42") are valid only for the newest observation; ... Call close_session when you are done.
Before you write or edit a test, read the writing-tests guide: the resource e2e://guide/writing-tests, or npx e2e guide writing-tests in a shell.
--- e2e://guide/writing-tests ---
# Writing tests
  • tests/integration/mcp-server.test.ts checks for the line in both places; both checks fail on main.