write-a-spec

Write and review Vitest unit specs with strict mocking, stub, and mutation-testing rules.

Updated Jul 28, 2026
One-click install
npx skills add https://github.com/oleg-vasilyev/FoolProof --skill write-a-spec-oleg-vasilyev
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: write-a-spec
Source: https://github.com/oleg-vasilyev/FoolProof/tree/main/.claude/skills/write-a-spec
Command: npx skills add https://github.com/oleg-vasilyev/FoolProof --skill write-a-spec-oleg-vasilyev

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Unit tests often exercise third-party libraries, reimplement fakes, or assert identities that pass regardless of correctness, leaving mutation survivors and false confidence. This Skill encodes the FoolProof repository's spec-writing rules so every *.spec.ts file tests exactly one module with everything else mocked. ## Core Features & Use Cases - Strict unit isolation: Enforces mocking every import — third-party libraries, sibling modules, and collaborators — while keeping data tables real, with rules for where shared constants must live. - Stub conventions: Defines typed stub classes with vi.fn() spy fields placed beside the modules they replace, plus guidance on hoisted vi.mock ordering and avoiding fakes that reimplement behavior. - Integration spec criteria: Limits integration specs to two shapes — contracts with external code and fully mocked module chains — documented in the an-integration-spec.md reference. - Mutation survivor analysis: The reading-a-survivor.md reference explains how to interpret Stryker survivors, distinguishing missing tests from equivalent mutants and dead code. - Use Case: When adding a new feature to the Telegram bot, use this Skill to write the spec first, deciding what the interfaces may expose based on what the spec can mock. ## Quick Start Use the write-a-spec skill to write a unit spec for the new card-message module following the repository's mocking and stub rules.

Frequently Asked Questions about write-a-spec

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write a unit test that mocks all imports in Vitest?▼

Declare spies first, call vi.mock for every imported module, then import the subject last because vi.mock is hoisted above imports. Reset with vi.clearAllMocks() in beforeEach and set default return values there so each case overrides one thing.

When should I write an integration test instead of a unit test?▼

Write an integration spec only for two shapes: a contract with code you did not write, or a chain of your own modules whose every joint is mocked. Name it *.integration.spec.ts and never write one merely because mocking was inconvenient.

Why does my Vitest mock not affect the module under test?▼

A vi.mock factory is untyped and hoisted, so a stub importing values from the mocked module reads uninitialized state. Give mocks values that differ from the real ones to prove the subject reads the mock, and keep shared constants in behavior-free modules.

What does a surviving mutant in Stryker mutation testing mean?▼

A survivor is a sentence about the spec, not always a missing test. Common causes include equivalent mutants, unasserted exact boundaries, dirty spies from prior tests, and assertions on absent values; print the mutant from the mutation report before deciding.

Should test fixtures use string literals or named constants?▼

Fixtures must spell states through named constants like CellKind.Fool, never raw strings, for discriminant properties such as kind, outcome, or phase. String literals remain acceptable only for external wire values and test data like player names.