mocha

name	mocha
description	Use when the user asks about Mocha test runner APIs and patterns for unit tests. Triggers on questions like "Mocha hooks", "before/after setup", "describe/it structure", "async tests in Mocha", "test timeouts", ".only/.skip", "how to run a specific test", or test organization.
allowed-tools	["Read","Bash","WebFetch","WebSearch"]

Mocha Documentation Lookup

This skill helps look up Mocha test runner APIs, patterns, and best practices for writing unit tests in this project.

Sources

Mocha Documentation

The official docs are a single-page site at https://mochajs.org/:

Topic	Anchor	Use For
Getting Started	#getting-started	Basic test structure
Assertions	#assertions	Assertion library integration
Async Tests	#asynchronous-code	Promises, async/await, callbacks
Hooks	#hooks	before, after, beforeEach, afterEach
Pending Tests	#pending-tests	Tests without implementation
Exclusive Tests	#exclusive-tests	.only usage (dev only, never commit)
Inclusive Tests	#inclusive-tests	.skip usage
Retry Tests	#retry-tests	this.retries() for flaky tests
Timeouts	#timeouts	Suite and test-level timeout configuration
Interfaces	#interfaces	BDD, TDD, exports, QUnit styles
Root Hook Plugins	#root-hook-plugins	Global setup/teardown

Process

1. Understand the Question Context

Determine whether the user needs:

• API reference: Exact hook behavior, configuration options, CLI flags
• Pattern guidance: How to structure tests, organize suites, handle async
• Troubleshooting: Timeout issues, hook ordering, test isolation
• Best practices: Project-specific conventions

2. Check Project Conventions First

Before fetching external docs, review the project's unit testing conventions from CLAUDE.md:

• Co-located .test.ts files using Mocha + Sinon + assert
• Focus on isolated behavior, mocking external dependencies
• Common stubs go in the top-level describe block
• No .only left in committed code
• Don't test side effects like logging
• Run tests: npx gulp test or npx gulp test -t "test name"

3. Fetch Documentation

Mocha docs are a single long page — use targeted prompts:

WebFetch: https://mochajs.org/
Prompt: "Find the documentation about [hooks / async tests / timeouts / etc.]"

For specific features or newer APIs, supplement with web search:

WebSearch: "mocha root hook plugin setup example"
WebSearch: "mocha beforeEach async teardown pattern"

4. Look at Existing Test Examples

When the user needs pattern guidance, look at how the project structures its tests:

# Find test files
find src -name "*.test.ts" | head -10

# Find tests using specific patterns
grep -r "beforeEach" --include="*.test.ts" -l src/ | head -5
grep -r "describe(" --include="*.test.ts" -l src/ | head -5

Read 1-2 relevant test files to show project-specific patterns alongside official docs.

Output Format

API Reference

## Mocha: [feature]

### API

[Description and behavior from docs]

### Example

[Code example from docs or adapted to project patterns]

### Project Usage

[How this is typically used in the project, with file references if found]

Pattern Guidance

## Pattern: [description]

### From the Docs

[Official recommended approach]

### In This Project

[How the project implements this pattern, with examples from existing tests]

### Key Points

- [Important considerations]
- [Common pitfalls to avoid]

Common Lookup Patterns

• Structure: describe(), it(), context()
• Hooks: before(), after(), beforeEach(), afterEach()
• Control: .only, .skip, this.timeout(), this.retries()
• Async: async/await, returning Promises, done callback
• Nesting: Nested describe blocks for organizing related tests
• Dynamic Tests: Generating tests in loops

Tips

• Mocha docs are a single long page — use targeted WebFetch prompts to extract the relevant section
• The project uses Node.js assert (not Chai) — adapt any Chai-based examples from docs to use assert.strictEqual, assert.deepStrictEqual, assert.ok, etc.
• Hook execution order matters: before runs once per describe, beforeEach runs before every it — the project convention is to put common stubs in the top-level describe's beforeEach
• Never commit .only — it restricts the test run. Use npx gulp test -t "name" for focused runs instead
• When answering "how to run tests" questions, reference the project's gulp commands rather than bare mocha CLI since the project uses @vscode/test-cli for test execution