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/:

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:

bash
1# Find test files
2find src -name "*.test.ts" | head -10
3
4# Find tests using specific patterns
5grep -r "beforeEach" --include="*.test.ts" -l src/ | head -5
6grep -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

markdown
1## Mocha: [feature]
2
3### API
4
5[Description and behavior from docs]
6
7### Example
8
9[Code example from docs or adapted to project patterns]
10
11### Project Usage
12
13[How this is typically used in the project, with file references if found]

Pattern Guidance

markdown
1## Pattern: [description]
2
3### From the Docs
4
5[Official recommended approach]
6
7### In This Project
8
9[How the project implements this pattern, with examples from existing tests]
10
11### Key Points
12
13- [Important considerations]
14- [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