docs: align testing principles with fewer longer tests

[kentcdodds]

Summary

• add Kent C. Dodds-style "fewer, longer tests" guidance to docs/agents/testing-principles.md
• align docs/agents/end-to-end-testing.md so E2E guidance also prefers workflow-shaped tests over splitting one journey into many tiny cases
• refactor high-signal MCP tests to follow those principles by removing brittle copy assertions and consolidating overlapping auth and MCP E2E workflows

Testing

• npm exec vitest run packages/worker/src/mcp/tools/execute.node.test.ts packages/worker/src/mcp-auth.workers.test.ts
• npm exec vitest --config vitest.mcp-e2e.config.ts run packages/worker/src/mcp/mcp-server.mcp-e2e.test.ts

  

Summary by CodeRabbit

• Documentation

  • Updated testing guidance to emphasize comprehensive end-to-end workflows over fragmented tests.
  • Refined assertions guidance to validate intermediate UI states within the same test journey.

• Tests

  • Refactored test suite to use consolidated assertion helpers and clearer variable naming for improved maintainability.
  • Aligned tests with updated end-to-end testing principles for better coverage consistency.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c48663f2-c0a7-4df2-94d2-eec8a90027b4

📥 Commits

Reviewing files that changed from the base of the PR and between 994e440 and d61f790.

📒 Files selected for processing (5)

• docs/agents/end-to-end-testing.md
• docs/agents/testing-principles.md
• packages/worker/src/mcp-auth.workers.test.ts
• packages/worker/src/mcp/mcp-server.mcp-e2e.test.ts
• packages/worker/src/mcp/tools/execute.node.test.ts

---

📝 Walkthrough

Walkthrough

The changes shift testing guidance and implementations from granular, isolated tests toward comprehensive end-to-end tests covering entire user journeys with multiple sequential assertions. Test implementations are refactored to use structured data validation instead of text parsing, with duplicated assertions consolidated into reusable helpers.

Changes

Cohort / File(s)	Summary
Documentation Updates docs/agents/end-to-end-testing.md, docs/agents/testing-principles.md	Updated guidance to favor fewer, longer E2E tests covering complete user journeys with multiple sequential actions and assertions in a single test, rather than splitting into isolated tiny tests with one assertion each. Intermediate UI states should be validated within the same test that triggers them.
Auth Test Consolidation packages/worker/src/mcp-auth.workers.test.ts	Added shared expectAuthenticateHeader helper to assert WWW-Authenticate header structure. Combined two separate protected resource metadata tests into one unified test; refactored two unauthorized-token tests to use the new helper, removing duplicated inline assertions.
MCP E2E Test Refactoring packages/worker/src/mcp/mcp-server.mcp-e2e.test.ts	Refactored multiple tests to use separate CallToolResult variables instead of reusing single instances. Shifted assertions from text content parsing to structuredContent field validation. Removed standalone tests for conversationId generation and saved app opening; embedded their logic into inline test blocks. Updated test titles to reflect context tracking intent.
Execute Tool Contract Testing packages/worker/src/mcp/tools/execute.node.test.ts	Renamed test to reflect tool contract validation intent. Replaced specific description substring assertions with broader contract checks covering tool name, definition structure (title, annotations, inputSchema), and handler function presence.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Add MCP conversation and memory context plumbing #103: Overlaps with MCP E2E and execute tool test changes related to conversationId/memoryContext handling and test structure modifications.
• Refine home connector router tests #102: Shares edits to docs/agents/testing-principles.md and shifts test assertions from brittle text parsing to behavior/structure-focused validation patterns.
• Adopt suffix-based Vitest test routing #67: Related to test file suffix changes (\*.mcp-e2e.test.ts) and Vitest test routing configuration that align with the refactored test structure.

Poem

🐰 Fewer tests, but oh so long,
Each journey flows like a winding song,
No scattered assertions scattered about,
One grand narrative, there is no doubt!
Structured truth blooms where helpers abound. ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly aligns with the primary change: updating documentation and test structure to favor fewer, longer tests per the stated objectives.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/mcp-e2e-test-consolidation-ab0e

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🔎 Preview deployed: https://kody-pr-105.kentcdodds.workers.dev

Worker: kody-pr-105
D1: kody-pr-105-db
KV: kody-pr-105-oauth-kv

Mocks:

• ai: https://kody-pr-105-mock-ai.kentcdodds.workers.dev/__mocks (kody-pr-105-mock-ai)
• cloudflare: https://kody-pr-105-mock-cloudflare.kentcdodds.workers.dev/__mocks (kody-pr-105-mock-cloudflare)
• cursor: https://kody-pr-105-mock-cursor.kentcdodds.workers.dev/__mocks (kody-pr-105-mock-cursor)
• github: https://kody-pr-105-mock-github.kentcdodds.workers.dev/__mocks (kody-pr-105-mock-github)
• resend: https://kody-pr-105-mock-resend.kentcdodds.workers.dev/__mocks (kody-pr-105-mock-resend)