/test-writer

name: test-writer
description: Generate comprehensive Vitest tests for code examples in JavaScript concept documentation pages, following project conventions and referencing source lines

Skill: Test Writer for Concept Pages

Use this skill to generate comprehensive Vitest tests for all code examples in a concept documentation page. Tests verify that code examples in the documentation are accurate and work as described.

When to Use

• After writing a new concept page
• When adding new code examples to existing pages
• When updating existing code examples
• To verify documentation accuracy through automated tests
• Before publishing to ensure all examples work correctly

Test Writing Methodology

Follow these four phases to create comprehensive tests for a concept page.

Phase 1: Code Example Extraction

Scan the concept page for all code examples and categorize them:

| Category | Characteristics | Action | |----------|-----------------|--------| | **Testable** | Has `console.log` with output comments, returns values | Write tests | | **DOM-specific** | Uses `document`, `window`, DOM APIs, event handlers | Write DOM tests (separate file) | | **Error examples** | Intentionally throws errors, demonstrates failures | Write tests with `toThrow` | | **Conceptual** | ASCII diagrams, pseudo-code, incomplete snippets | Skip (document why) | | **Browser-only** | Uses browser APIs not available in jsdom | Skip or mock |

Phase 2: Determine Test File Structure

tests/
├── fundamentals/              # Concepts 1-6
├── functions-execution/       # Concepts 7-8
├── web-platform/             # Concepts 9-10
├── object-oriented/          # Concepts 11-15
├── functional-programming/   # Concepts 16-19
├── async-javascript/         # Concepts 20-22
├── advanced-topics/          # Concepts 23-31
└── beyond/                   # Extended concepts
    └── {subcategory}/

**File naming:**

• Standard tests: `{concept-name}.test.js`
• DOM tests: `{concept-name}.dom.test.js`

Phase 3: Convert Examples to Tests

For each testable code example:

1. Identify the expected output (from `console.log` comments or documented behavior) 2. Convert to `expect` assertions 3. Add source line reference in comments 4. Group related tests in `describe` blocks matching documentation sections

Phase 4: Handle Special Cases

| Case | Solution | |------|----------| | Browser-only APIs | Use jsdom environment or skip with note | | Timing-dependent code | Use `vi.useFakeTimers()` or test the logic, not timing | | Side effects | Capture output or test mutations | | Intentional errors | Use `expect(() => {...}).toThrow()` | | Async code | Use `async/await` with proper assertions |

---

Project Test Conventions

Import Pattern

import { describe, it, expect } from 'vitest'

For DOM tests or tests needing mocks:

import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'

DOM Test File Header

/**
 * @vitest-environment jsdom
 */
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'

Describe Block Organization

Match the structure of the documentation:

describe('Concept Name', () => {
  describe('Section from Documentation', () => {
    describe('Subsection if needed', () => {
      it('should [specific behavior]', () => {
        // Test
      })
    })
  })
})

Test Naming Convention

• Start with "should"
• Be descriptive and specific
• Match the documented behavior

// Good
it('should return "object" for typeof null', () => {})
it('should throw TypeError when accessing property of undefined', () => {})
it('should resolve promises in order they were created', () => {})

// Bad
it('test typeof', () => {})
it('works correctly', () => {})
it('null test', () => {})

Source Line References

Always reference the documentation source:

// ============================================================
// SECTION NAME FROM DOCUMENTATION
// From {concept}.mdx lines XX-YY
// ============================================================

describe('Section Name', () => {
  // From lines 45-52: Basic typeof examples
  it('should return correct type strings', () => {
    // Test
  })
})

---

Test Patterns Reference

Pattern 1: Basic Value Assertion

**Documentation:**

console.log(typeof "hello")  // "string"
console.log(typeof 42)       // "number"

**Test:**

// From lines XX-YY: typeof examples
it('should return correct type for primitives', () => {
  expect(typeof "hello").toBe("string")
  expect(typeof 42).toBe("number")
})

---

Pattern 2: Multiple Related Assertions

**Documentation:**

let a = "hello"
let b = "hello"
console.log(a === b)  // true

let obj1 = { x: 1 }
let obj2 = { x: 1 }
console.log(obj1 === obj2)  // false

**Test:**

// From lines XX-YY: Primitive vs object comparison
it('should compare primitives by value', () => {
  let a = "hello"
  let b = "hello"
  expect(a === b).toBe(true)
})

it('should compare objects by reference', () => {
  let obj1 = { x: 1 }
  let obj2 = { x: 1 }
  expect(obj1 === obj2).toBe(false)
})

---

Pattern 3: Function Return Values

**Documentation:**

function greet(name) {
  return "Hello, " + name + "!"
}

console.log(greet("Alice"))  // "Hello, Alice!"

**Test:**

// From lines XX-YY: greet function example
it('should return greeting with name', () => {
  function greet(name) {
    return "Hello, " + name + "!"
  }
  
  expect(greet("Alice")).toBe("Hello, Alice!")
})

---

Pattern 4: Error Testing

**Documentation:**

// This throws an error!
const obj = null
console.log(obj.property)  // TypeError: Cannot read property of null

**Test:**

// From lines XX-YY: Accessing property of null
it('should throw TypeError when accessing property of null', ()