# Real World Testing

Use when fixing a bug, writing or reviewing tests, or adding a regression test anywhere...

- Repository: https://github.com/mastra-ai/mastra (29259 stars)
- Category: Testing
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add mastra-ai/mastra --skill real-world-testing -g -a claude-code -y`
Codex: `npx skills add mastra-ai/mastra --skill real-world-testing -g -a codex -y`
Cursor: `npx skills add mastra-ai/mastra --skill real-world-testing -g -a cursor -y`
Gemini CLI: `npx skills add mastra-ai/mastra --skill real-world-testing -g -a gemini-cli -y`

## Description

Use when fixing a bug, writing or reviewing tests, or adding a regression test anywhere in Mastra (core, storage adapters, server adapters, memory, client SDKs, integrations). Especially use before mocking a class, model, storage, or server; before writing a unit test that only checks wiring or that a value is defined; before writing a one-off test for a single engine, adapter, or code path; before adding a recorded (__recordings__) fixture; or when a test passes but you aren't sure it reproduces the real failure.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Real-world testing

Tests exist to make Mastra work for the people building on it. A test earns its place only if it would have caught a bug a user hit, or will catch the next one. A test that passes while the real app is broken is worse than no test: it says things are fine, it costs time to run and maintain, and it breaks on harmless refactors.

Every test you add should answer: **what real failure does this protect against?** If you can't name one, don't write the test.

## Tests that don't earn their place

Don't write these. When you find them next to code you're changing, replace or delete them.

- **Smoke tests that assert nothing real**: `expect(result.runId).toBeDefined()`, `expect(fn).not.toThrow()`, "it returns something".
- **Mock-echo tests**: mock a dependency, call the code, then assert the mock was called with what you passed in. This tests the mock, not the behavior.
- **Implementation mirrors**: tests that restate the code line by line (private helpers, internal call order, exact intermediate objects). They break on every refactor and catch no user-facing bug.
- **Mocked-out boundaries**: `vi.fn()` storage, stubbed `fetch`, fake `Mastra` or agent classes, mocked processors. The bug usually lives in the code you mocked away.
- **Single-path copies**: the same case rewritten for one engine, adapter, or provider, so a fix in one path never gets checked in the others.
- **Snapshots of internals** nobody reads when they change.

Unit tests are fine for pure logic with real edge cases (a parser, a schema converter, a scheduling or retry calculation) where inputs and outputs are the contract. Test those inputs and outputs, not the steps in between.

## Principles

The rest: https://github.com/mastra-ai/mastra/blob/HEAD/.agents/skills/real-world-testing/SKILL.md