Testing Plan

This document defines a detailed testing plan for the Software Project Management MCP server and the TODO engine library (ProjectMcp.TodoEngine). It covers unit, integration, end-to-end, and manual testing; test data; environments; and quality gates. It aligns with 04 — MCP Surface, 10 — MCP Endpoint Diagrams, 06 — Tech Requirements, and 19 — TODO Library Implementation.

Note: Work items and tasks are the same entity; a task is a work item with level = Task. Test cases that mention tasks apply to work_items at level = Task.

1. Testing pyramid and objectives

Objectives:

• All tool and resource endpoints have at least one happy-path test (integration or E2E).
• The TODO engine library (View, SlugService, scope enforcement, AuditContext) has unit tests (with mocks) and integration tests (with real DB) in isolation; see §2.3, §3.5.
• Path safety and input validation have dedicated unit tests where applicable.
• No secrets in tests; use env or test-specific config for DB.
• CI runs unit and integration tests on every commit; E2E optionally on schedule or tag.

2. Unit tests

2.1 Scope and responsibilities

• Handlers / service logic: Given valid/invalid inputs, assert returned result or thrown validation.
• Path resolution (if any file-path tool exists): Resolve path relative to root; reject .., absolute paths outside root, null/empty.
• DTO / request parsing: Deserialize tool arguments; validate required fields and types.
• Slug/ID resolution: If implemented in a dedicated service, test slug → GUID resolution and invalid slug handling.
• TODO library — SlugService (unit): Allocate slug format (e.g. WI000001, E1-P001-REQ0001), next index per owner/entity type, invalid owner or entity type.
• TODO library — View (unit, mocked repos): View methods with valid scope return expected DTOs; with scope for different enterprise, throw or return scope violation (ScopeViolationException or equivalent); GetProject(scope) returns null when project not in scope.
• TODO library — DI: After AddTodoEngine(services, options), resolve ITodoView, ISlugService, and key repositories from ServiceProvider; ensure no missing registration.

2.2 Test project layout

tests/
  ProjectMcp.Tests.Unit/
    Handlers/
      ScopeSetHandlerTests.cs
      EnterpriseHandlerTests.cs
      ProjectGetInfoHandlerTests.cs
      ProjectUpdateHandlerTests.cs
      RequirementHandlerTests.cs
      StandardHandlerTests.cs
      WorkItemHandlerTests.cs
      TaskCreateHandlerTests.cs
      TaskUpdateHandlerTests.cs
      TaskListHandlerTests.cs
      TaskDeleteHandlerTests.cs
      IssueHandlerTests.cs
      MilestoneHandlerTests.cs
      ReleaseHandlerTests.cs
      DomainHandlerTests.cs
      SystemHandlerTests.cs
      AssetHandlerTests.cs
      ResourceHandlerTests.cs
      KeywordHandlerTests.cs
      WorkQueueHandlerTests.cs
      AssociationHandlerTests.cs
      DocRegisterHandlerTests.cs
      DocListHandlerTests.cs
    Services/
      PathResolverTests.cs
      SessionStoreTests.cs
    TodoEngine/
      SlugServiceTests.cs
      TodoViewUnitTests.cs
      TodoEngineDiTests.cs
    Validation/
      ProjectUpdateValidatorTests.cs
      RequirementCreateValidatorTests.cs
      WorkItemCreateValidatorTests.cs
      TaskCreateValidatorTests.cs

2.3 Key unit test cases

2.4 Tool response shape

• Unit tests that assert tool response shape (e.g. JSON with expected keys, or error with error and isError: true) without hitting the database.

2.5 Coverage expectations

• Target: ≥ 80% line coverage for handler/service and path-resolution code, and for TODO engine library code (View, SlugService, scope validation).
• Exclude: MCP SDK glue, main entry point, trivial DTOs, and generated/migration code.
• CI: Fail the build if coverage drops below a threshold (e.g. 75%) or if new code in covered areas has no tests.

3. Integration tests

3.1 Scope and responsibilities

• Database: Real PostgreSQL (Testcontainers or CI-provided service). Apply migrations before tests; optionally seed minimal data.
• Repositories / DbContext: Create enterprise, project, requirement, standard, work item, task, issue, domain, system, asset, resource, keyword, milestone, release; read and update; delete. Assert persistence and scope (e.g. task list filtered by project_id).
• Session store: If backed by DB or shared state, test context_key → scope resolution and scope_set/scope_get across “requests.”
• Full tool flow with DB: Call handler with valid scope and params; handler uses real repository; assert DB state and response (e.g. work_item_create inserts row, work_item_list returns it).

3.2 Test database setup

• Option A: Testcontainers — start Postgres container per test run or per class; run migrations; run tests; dispose.
• Option B: CI service (e.g. GitHub Actions Postgres service); run migrations once; use unique schema or DB per run if parallel.
• Connection string: From env (e.g. TEST_DATABASE_URL) or Testcontainers-generated URL. No hardcoded credentials.

3.3 Test project layout

tests/
  ProjectMcp.Tests.Integration/
    Data/
      EnterpriseRepositoryTests.cs
      ProjectRepositoryTests.cs
      RequirementRepositoryTests.cs
      StandardRepositoryTests.cs
      WorkItemRepositoryTests.cs
      TaskRepositoryTests.cs
      IssueRepositoryTests.cs
      MilestoneRepositoryTests.cs
      ReleaseRepositoryTests.cs
      DomainRepositoryTests.cs
      SystemRepositoryTests.cs
      AssetRepositoryTests.cs
      ResourceRepositoryTests.cs
      KeywordRepositoryTests.cs
      AssociationRepositoryTests.cs
      DocRepositoryTests.cs
    HandlersWithDb/
      ScopeIntegrationTests.cs
      EnterpriseToolsIntegrationTests.cs
      ProjectToolsIntegrationTests.cs
      RequirementToolsIntegrationTests.cs
      StandardToolsIntegrationTests.cs
      WorkItemToolsIntegrationTests.cs
      TaskToolsIntegrationTests.cs
      IssueToolsIntegrationTests.cs
      PlanningToolsIntegrationTests.cs
      DomainToolsIntegrationTests.cs
      SystemToolsIntegrationTests.cs
      AssetToolsIntegrationTests.cs
      ResourceToolsIntegrationTests.cs
      KeywordToolsIntegrationTests.cs
      WorkQueueIntegrationTests.cs
      AssociationToolsIntegrationTests.cs
      DocToolsIntegrationTests.cs
    Resources/
      ResourceSpecIntegrationTests.cs
      ResourceTasksIntegrationTests.cs
      ResourcePlanIntegrationTests.cs
    TodoEngine/
      TodoViewIntegrationTests.cs
      SlugServiceIntegrationTests.cs
      TodoEngineScopeAndAuditTests.cs

3.4 Key integration test cases

3.5 TODO engine library (integration, in isolation)

The TODO engine library (19 — TODO Library Implementation) is testable in isolation with a real database (Testcontainers Postgres or in-memory SQLite). These tests verify the View, SlugService, repositories, scope enforcement, and audit context propagation without the MCP host.

Test project layout: Either a dedicated ProjectMcp.TodoEngine.Tests project or a folder under integration tests, e.g. tests/ProjectMcp.Tests.Integration/TodoEngine/ with TodoViewIntegrationTests.cs, SlugServiceIntegrationTests.cs, TodoEngineScopeAndAuditTests.cs.

3.6 Isolation and cleanup

• Each test that mutates data should use a dedicated project/enterprise (e.g. unique GUID or slug) or run in a transaction that is rolled back so tests do not affect each other.
• Avoid shared mutable state; prefer fresh DB or transaction rollback per test.
• TODO library tests: Use a fresh DbContext (or new container) per test class or test method so slug allocation and scope tests do not interfere.

4. End-to-end (E2E) tests

4.1 Scope and responsibilities

• Full MCP protocol (stdio or REST): Start server process; send Initialize request (stdio or POST /mcp/initialize); receive response with context_key and tool list. Send tool calls (with context_key via envelope or X-Context-Key header); assert response content. Optionally request resources. Both transports should be covered (e.g. E2E for stdio, E2E for REST).
• Real server process: Either in-process server with stdio pipes or subprocess (e.g. dotnet run); for REST, run HTTP host and send HTTP requests. Database can be Testcontainers or dedicated E2E DB.

4.2 E2E test flow (example)

1. Start Postgres (Testcontainers or env); run migrations; optionally seed one enterprise and one project.
2. Start MCP server process with connection string and default scope (or no default).
3. Send Initialize (client name, version, capabilities).
4. Parse Initialize response; extract context_key.
5. Send scope_set(scope_slug) with context_key; assert success and scope in response.
6. Send project_get_info with context_key; assert project metadata (or empty).
7. Send project_update with context_key; assert success.
8. Send project_get_info again; assert updated data.
9. Send task_create(title: “E2E task”) with context_key; assert task in response.
10. Send project://current/tasks resource read with context_key; assert task list contains the created task.
11. Send task_list with context_key; assert list contains the task.
12. Send task_update(id, status: “done”); then task_list; assert status updated.
13. Send task_delete(id); then task_list; assert task gone.
14. (Optional) Send requirement_create, work_item_create, issue_create, and domain_create; assert list results.
15. (Optional) Send milestone_create, release_create; assert success.
16. (Optional) Attempt out-of-scope read/write (different enterprise); assert 403 + log entry.
17. Shut down server process.

4.3 E2E implementation options

Recommendation: Start with subprocess and simple JSON over stdin/stdout (or use MCP client if available for .NET) so E2E truly validates the full stack.

4.4 E2E test layout and CI

• Location: e.g. tests/ProjectMcp.Tests.E2E/ or a dedicated E2E solution/folder.
• CI: Run on main/PR with Testcontainers Postgres; optionally run on schedule or only on release tag to keep PR feedback fast.
• Timeout: E2E suite should have a global timeout (e.g. 2–5 minutes) and per-test timeouts to avoid hangs.

5. Cursor agent CLI script-driven integration test

This test validates that a real agent (Cursor agent CLI), driving a locally running ProjectMCP instance, can “build this project in the MCP” by following a script of prompts. After each prompt, the test compares the database state to an expected state before submitting the next prompt. It ensures the agent’s use of tools and resources produces the intended persisted state at every step.

5.1 Purpose and scope

• Purpose: Confirm that the ProjectMCP server behaves correctly when consumed by the Cursor agent CLI: the agent can set scope, create/update project and tasks, milestones, releases, and docs in response to natural-language prompts, and the resulting database state matches expectations at each step.
• Scope: Integration test (real agent, real local server, real database). Requires Cursor agent CLI to be available and a script that submits prompts and then runs DB assertions.
• Skip condition: If the Cursor agent CLI is not installed or not on PATH, skip the test and report the reason.

5.2 Prerequisites

5.3 Test flow

1. Setup
   • Start or attach to a Postgres instance (e.g. Testcontainers); apply migrations; optionally seed one enterprise (and optionally one project) so the agent can set scope.
   • Start the ProjectMCP server process pointing at this database (or ensure the Cursor agent CLI is configured to start/use this server).
   • Load the prompt script (see below).
   • Record initial DB state (e.g. row counts for project, task, milestone, release; or full snapshot of relevant tables).
2. For each step in the script (in order):
   • Submit prompt: Send the next prompt from the script to the Cursor agent CLI (e.g. via CLI stdin or a driver that invokes the CLI with the prompt).
   • Wait for completion: Wait until the agent has finished (CLI exits or signals completion). Use a timeout to avoid hangs.
   • Capture DB state: Query the database for the state relevant to the test (e.g. all projects for the test enterprise, all tasks for the test project, milestones, releases).
   • Compare to expected state: Compare the captured state to the expected state for this step (defined in the script or a companion file). Comparison may be:
     • Row counts and key fields (e.g. one project with name “ProjectMcp”, two tasks with titles matching expected).
     • Or a full snapshot (e.g. JSON export of project/tasks/milestones/releases) diffed against a golden file.
   • Pass/fail: If the state does not match the expected state, fail the test and optionally capture logs and DB dump for debugging. Do not continue to the next prompt.
   • If the state matches, continue to the next step.
3. Teardown
   • Stop the server (if started by the test).
   • Optionally tear down the database (Testcontainers dispose) or leave it for artifact collection on failure.

5.4 Prompt script: “Build this project in the MCP”

The script is a ordered list of prompts (and, per step, the expected DB state after the agent has acted on that prompt). The goal of the scenario is to have the agent “build this project in the MCP”—i.e. create and update project metadata, tasks, and planning in ProjectMCP to reflect the ProjectMcp repo (or a minimal version of it).

Example structure (prompts and expectations are illustrative):

The actual prompt script and expected state (e.g. JSON or table) should live in the repo (e.g. tests/ProjectMcp.Tests.Integration/CursorAgentScript/ or similar) so they can be versioned and updated when the scenario or schema changes.

5.5 Expected state format and comparison

• Format: Expected state can be defined as:
  • Structured file (recommended): e.g. JSON or YAML per step: step-01-expected.json, … listing expected entities (projects, tasks, milestones, releases) with key fields (id optional, name, title, status, etc.). The test loads this file and compares to the DB snapshot (normalizing order if needed, e.g. sort by id or title).
  • Inline in script: Script file has a section per step: prompt text plus expected state (table or mini-DSL).
• Comparison: Compare only the fields that the agent is expected to have set (e.g. name, title, status, count). Ignore generated ids and timestamps unless they are needed for ordering. Use tolerant comparison (e.g. trim strings, ignore irrelevant tables).

5.6 Implementation options

Recommendation: Implement a script runner (e.g. in the test project or a scripts/ directory) that: (1) ensures the server and DB are up, (2) runs the Cursor agent CLI for each prompt in order, (3) after each step runs a DB assertion (e.g. a small tool or script that queries the DB and diffs to expected state), (4) exits with non-zero if any step’s state does not match. The main test (xUnit or similar) can then invoke this runner and assert exit code zero, or the runner can be the test itself in a separate step in CI.

5.7 Test layout and CI

• Location: e.g. tests/ProjectMcp.Tests.Integration/CursorAgentScript/ with:
  • prompts.yaml or prompts.json — ordered list of { prompt, expectedStateFile }.
  • expected/step-01-expected.json, etc.
  • Runner: RunCursorAgentScript.cs (or a shell script run-cursor-agent-test.sh) that executes the flow above.
• CI: Run only when Cursor agent CLI is available (e.g. optional job or conditional step); or run on schedule/nightly. Use a dedicated test DB (Testcontainers or CI Postgres) and a known-good server build (e.g. dotnet run or published binary).
• Timeout: Per-prompt timeout (e.g. 60–120 seconds) and global script timeout (e.g. 10–15 minutes) to avoid hangs.

5.8 Failure handling

• On state mismatch: Fail immediately; log the prompt index, expected vs actual state (or diff); optionally capture server logs and a DB dump (e.g. pg_dump or export of relevant tables) as artifacts.
• On CLI timeout or crash: Fail the test; capture stdout/stderr and server logs for debugging.

6. Manual testing

6.1 Manual test checklist

Use this with Cursor (or another MCP client) after deployment or before release.

6.2 Exploratory testing

• Switch scope (scope_set to different project); verify project_get_info and task_list reflect new scope.
• Large task list; filters (status, assignee, milestoneId); confirm performance and correctness.
• Invalid inputs: missing title on task_create, missing id on task_update; confirm structured error and no crash.

7. Test data and fixtures

7.1 Minimal seed (integration/E2E)

• Enterprise: 1 row (e.g. id, name “Test Enterprise”).
• Project: 1 row (enterprise_id, name “Test Project”, status active).
• Requirements: 0–2 requirements (optional) for list/filter tests.
• Work items: 0–2 work items (optional) for list/filter tests.
• Tasks: 0–2 tasks (optional) for list/filter tests.
• Milestone: 1 (optional) for milestone_id filter.
• Release: 1 (optional) for release_id.

7.2 Fixtures and builders

• Use in-memory builders or small fixture classes to create valid DTOs (e.g. CreateTaskRequest with default title) to keep test code readable and avoid duplication.
• No production data; all test data is synthetic and safe to delete or roll back.

8. Environments and configuration

• Secrets: Never commit connection strings or API keys. Use env vars or secret store in CI and staging/prod.
• Test env vars: Document in README or CI workflow: e.g. TEST_DATABASE_URL.

9. Quality gates and CI

10. Summary table: what to test where

Blazor Web App: Excruciatingly detailed testing for the web app (auth, scope, tree, search, reports, Gantt, issues, SUDO) is in 24 — Blazor Web App Testing Plan.

This plan ensures coverage of all MCP endpoints, path safety, validation, and scope; supports CI quality gates; includes a Cursor agent CLI script-driven integration test that asserts database state after each prompt; and provides a clear manual checklist for release.