QA Test Workflows from Your Story Map

The Coverage Gap

Most test suites are written after the code, based on what the implementation happens to do. The tests end up mirroring the code structure: one test file per module, one assertion per function, instead of mirroring the user journey.

Meanwhile, your story map already describes the flows that matter: each journey is a user workflow, each step is a meaningful action, and each risk card is an edge case your team has already thought about. That map has not been connected to your test suite yet.

What You Need

• A coding agent, such as Claude Code, Cursor, or similar, with the Cartographer MCP server connected.
• A story map with journeys, steps, and story cards that describe your user flows. The more detail on the cards, descriptions, persona tags, risk and question cards, the better the generated tests.
• A test framework in your project: Playwright, Cypress, Vitest, Jest, or similar. The coding agent writes tests in whatever framework you already use.

The Workflow

Your story map describes what users do. Your test suite verifies that it works. The coding agent connects the two by reading the map and writing tests that match the structure of your user journeys, not just the structure of your code.

Read the Journey Structure

Ask your coding agent to read the story map using projects_list_backbone. This returns the journey and step hierarchy: the high-level structure of everything users do in your product.

Each journey maps to a test suite (or describe block). Each step under a journey maps to a group of related test cases. The backbone gives the coding agent the organizational structure before it looks at individual cards.

Generate Test Cases from Steps

For each step, the coding agent reads the full card details using projects_get_card_details. Story cards under a step become individual test cases. A card titled “User uploads CSV file” becomes a test that verifies CSV upload works. A card titled “System validates file format” becomes a test that checks validation behavior.

Card descriptions provide the detail behind the test title. A description like “Users should see a preview of the first 10 rows before confirming the import” gives the coding agent enough context to write a meaningful assertion rather than a placeholder.

Use Risk Cards for Edge Cases

risk cards are edge cases your team already identified during planning. “File exceeds 100MB limit” becomes a boundary test. “Network drops during upload” becomes a resilience test. “User uploads duplicate file” becomes a conflict handling test.

These are the tests that usually get missed because they require someone to think adversarially about the feature. Your team already did that thinking during story mapping: the risk cards are the evidence. The coding agent turns them into negative test cases.

Use Personas for Test Variations

Cards tagged with different personas produce different test scenarios. The same “View dashboard” step tested as an Admin persona includes permission-gated elements. Tested as a New User persona, it checks for onboarding prompts and empty states.

The coding agent reads persona tags from cards and generates test variants. A single step with three persona tags produces three test groups, each exercising the feature from a different user’s perspective.

Write the Actual Tests

The coding agent writes test code. For end-to-end flows, it writes Playwright or Cypress tests that navigate through the journey step by step. For individual cards, it writes unit or integration tests using your existing framework.

Because the agent has access to both the story map (via MCP) and your codebase (via the file system), it maps card descriptions to actual UI elements, API endpoints, and component names. The tests reference selectors and routes that exist in your codebase, not placeholders.

Example Session

1. Read the map. “Read the story map and list all journeys.” The coding agent calls projects_list_backbone and returns the journey/step tree.
2. Pick a journey. “Generate tests for the File Import journey.” The agent reads all cards under that journey’s steps, including risk and question cards.
3. Generate the test file. The agent creates file-import.spec.ts with a describe block for each step. Happy-path tests come from story cards. Edge-case tests come from risk cards. Persona-variant tests come from persona tags.
4. Review and refine. You review the generated tests, adjust selectors or setup logic, and run them. The agent updates tests based on your feedback.
5. Track coverage. The agent adds a comment to each card noting that tests have been written, so anyone reading the card can see it has test coverage.

Keeping Tests in Sync

When the map changes, your tests should change too. New cards mean new test cases, resolved risk cards can simplify edge-case tests, and new question cards can highlight flows that need exploratory testing before they get automated.

Ask your coding agent to compare the current map against existing test files. It reads the map, scans your test directory, and identifies gaps: steps with no corresponding tests, risk cards with no negative test cases, and new cards added since the last test generation pass.

Tips

• Start with one journey. Do not try to generate tests for the entire map at once. Pick the most critical user journey, generate tests for it, and refine the process before moving to other journeys.
• Write card descriptions for testability. Descriptions like “user sees a success message” are more testable than “upload works.”
• Use risk cards often. The highest-value tests are the ones that catch edge cases. Every risk your team has identified is a test case that would otherwise be missed. Add risk cards generously during planning.
• Tag cards with question for manual testing. Not everything can be automated. question cards often represent ambiguity that needs human judgment. Use them to build a manual test checklist alongside the automated suite.
• Link tests back to cards. Add comments on cards when tests are written, and reference card IDs in test descriptions. This two-way link makes it easy to trace a test failure back to the requirement it covers and to see which cards have test coverage.