Skip to main content
Was this helpful?

Testing Strategy

PrimeCal uses layered testing. Start with the cheapest layer that can prove behavior, then climb to heavier layers when risk increases.

Core Commands​

  • Fast local regression: npm test
  • Backend unit: npm --prefix backend-nestjs run test:unit
  • Backend integration: npm --prefix backend-nestjs run test:integration
  • Backend e2e: npm --prefix backend-nestjs run test:e2e
  • MCP integration + protocol conformance: npm --prefix backend-nestjs run test:mcp:integration
  • MCP security: npm --prefix backend-nestjs run test:mcp:security
  • MCP browser e2e: npm run test:e2e:mcp-browser

MCP Test Layers​

1) Unit (fast)​

  • backend-nestjs/src/mcp-server/*.spec.ts
  • Focus:
    • Tool/resource registration and schema shape
    • API-key auth parsing and permission filtering
    • Error mapping into MCP tool + JSON-RPC envelopes
    • Adapter normalization (AgentMcpService) for tool input/output contracts

2) Integration (testcontainers + real Nest app)​

  • backend-nestjs/test/integration/agents-mcp-edge.integration-spec.ts
  • backend-nestjs/test/integration/mcp-protocol-conformance.integration-spec.ts
  • Focus:
    • initialize handshake + session flow
    • tools/list, resources/list, resources/read, tools/call
    • Calendar/task/automation/profile/context domain flows through MCP
    • Permission scope enforcement (calendarIds, ruleIds)
    • Validation errors, invalid keys, and temporary backend failures

3) Security integration​

  • backend-nestjs/test/security/agent-mcp.security-spec.ts
  • Focus:
    • Auth header behavior (Agent, Bearer ag_sk_..., missing/invalid)
    • Revoked key behavior
    • Rate-limit behavior and secure MCP error envelopes

4) Browser e2e (UI + MCP + backend)​

  • e2e/web/mcp-browser-sync.spec.ts
  • Config: e2e/playwright.mcp.config.ts
  • Flow:
    • Start frontend + backend
    • Create test user and MCP agent key
    • Create task via MCP tool
    • Verify the task appears in UI for the same user

CI Gates​

PR + main CI executes:

  • ci:backend-core (includes MCP unit tests)
  • ci:backend-integration
  • ci:mcp-integration
  • ci:mcp-security

main push + workflow dispatch additionally execute:

  • ci:mcp-browser-e2e

If MCP tests fail, CI fails.

MCP Availability Policy​

  • MCP is permanently supported.
  • No MCP feature flag controls test or production availability.
  • Access is controlled only by:
    • running MCP process/endpoint
    • valid agent API key authentication
    • per-agent permission scopes

Troubleshooting​

  • 401 on initialize: invalid/revoked key or missing Agent/Bearer ag_sk_... header.
  • 400 on MCP calls: initialize first, then send mcp-session-id.
  • Tool missing from tools/list: agent permission does not allow it.
  • Scope-denied calls: check calendarIds/ruleIds in assigned permissions.
  • Browser MCP e2e connectivity issues: verify backend 8081, frontend 4173, and SECURITY_ALLOWED_ORIGINS.
  • Docker-backed integration failures: ensure Docker is running and ENABLE_TESTCONTAINERS=true.