test-specialist

---

name: test-specialist description: This skill should be used when writing test cases, fixing bugs, analyzing code for potential issues, or improving test coverage for JavaScript/TypeScript applications. Use this for unit tests, integration tests, end-to-end tests, debugging runtime errors, logic bugs, performance issues, security vulnerabilities, and systematic code analysis.

Test Specialist

Overview

Apply systematic testing methodologies and debugging techniques to JavaScript/TypeScript applications. This skill provides comprehensive testing strategies, bug analysis frameworks, and automated tools for identifying coverage gaps and untested code.

Core Capabilities

1. Writing Test Cases

Write comprehensive tests covering unit, integration, and end-to-end scenarios.

Unit Testing Approach

Structure tests using the AAA pattern (Arrange-Act-Assert):

describe('ExpenseCalculator', () => {
  describe('calculateTotal', () => {
    test('sums expense amounts correctly', () => {
      // Arrange
      const expenses = [
        { amount: 100, category: 'food' },
        { amount: 50, category: 'transport' },
        { amount: 25, category: 'entertainment' }
      ];

      // Act
      const total = calculateTotal(expenses);

      // Assert
      expect(total).toBe(175);
    });

    test('handles empty expense list', () => {
      expect(calculateTotal([])).toBe(0);
    });

    test('handles negative amounts', () => {
      const expenses = [
        { amount: 100, category: 'food' },
        { amount: -50, category: 'refund' }
      ];
      expect(calculateTotal(expenses)).toBe(50);
    });
  });
});

Key principles:

• Test one behavior per test
• Cover happy path, edge cases, and error conditions
• Use descriptive test names that explain the scenario
• Keep tests independent and isolated

Integration Testing Approach

Test how components work together, including database, API, and service interactions:

describe('ExpenseAPI Integration', () => {
  beforeAll(async () => {
    await database.connect(TEST_DB_URL);
  });

  afterAll(async () => {
    await database.disconnect();
  });

  beforeEach(async () => {
    await database.clear();
    await seedTestData();
  });

  test('POST /expenses creates expense and updates total', async () => {
    const response = await request(app)
      .post('/api/expenses')
      .send({
        amount: 50,
        category: 'food',
        description: 'Lunch'
      })
      .expect(201);

    expect(response.body).toMatchObject({
      id: expect.any(Number),
      amount: 50,
      category: 'food'
    });

    // Verify database state
    const total = await getTotalExpenses();
    expect(total).toBe(50);
  });
});

End-to-End Testing Approach

Test complete user workflows using tools like Playwright or Cypress:

test('user can track expense from start to finish', async ({ page }) => {
  // Navigate to app
  await page.goto('/');

  // Add new expense
  await page.click('[data-testid="add-expense-btn"]');
  await page.fill('[data-testid="amount"]', '50.00');
  await page.selectOption('[data-testid="category"]', 'food');
  await page.fill('[data-testid="description"]', 'Lunch');
  await page.click('[data-testid="submit"]');

  // Verify expense appears in list
  await expect(page.locator('[data-testid="expense-item"]')).toContainText('Lunch');
  await expect(page.locator('[data-testid="total"]')).toContainText('$50.00');
});

2. Systematic Bug Analysis

Apply structured debugging methodology to identify and fix issues.

Five-Step Analysis Process

1. Reproduction: Reliably reproduce the bug

   • Document exact steps to trigger
   • Identify required environment/state
   • Note expected vs actual behavior

2. Isolation: Narrow down the problem

   • Binary search through code path
   • Create minimal reproduction case
   • Remove unrelated dependencies

3. Root Cause Analysis: Determine underlying cause

   • Trace execution flow
   • Check assumptions and preconditions
   • Review recent changes (git blame)

4. Fix Implementation: Implement solution

   • Write failing test first (TDD)
   • Implement the fix
   • Verify test passes

5. Validation: Ensure completeness

   • Run full test suite
   • Test edge cases
   • Verify no regressions

Common Bug Patterns

Race Conditions:

// Test concurrent operations
test('handles concurrent updates correctly', async () => {
  const promises = Array.from({ length: 100 }, () =>
    incrementExpenseCount()
  );

  await Promise.all(promises);
  expect(getExpenseCount()).toBe(100);
});

Null/Undefined Errors:

// Test null safety
test.each([null, undefined, '', 0, false])
  ('handles invalid input: %p', (input) => {
    expect(() => processExpense(input)).toThrow('Invalid expense');
  });

Off-by-One Errors:

// Test boundaries explicitly
describe('pagination', () => {
  test('handles empty list', () => {
    expect(paginate([], 1, 10)).toEqual([]);
  });

  test('handles single item', () => {
    expect(paginate([item], 1, 10)).toEqual([item]);
  });

  test('handles last page with partial items', () => {
    const items = Array.from({ length: 25 }, (_, i) => i);
    expect(paginate(items, 3, 10)).toHaveLength(5);
  });
});

3. Identifying Potential Issues

Proactively identify issues before they become bugs.

Security Vulnerabilities

Test for common security issues:

describe('security', () => {
  test('prevents SQL injection', async () => {
    const malicious = "'; DROP TABLE expenses; --";
    await expect(
      searchExpenses(malicious)
    ).resolves.not.toThrow();
  });

  test('sanitizes XSS in descriptions', () => {
    const xss = '<script>alert("xss")</script>';
    const expense = createExpense({ description: xss });
    expect(expense.description).not.toContain('<script>');
  });

  test('requires authentication for expense operations', async () => {
    await request(app)
      .post('/api/expenses')
      .send({ amount: 50 })
      .expect(401);
  });
});

Performance Issues

Test for performance problems:

test('processes large expense list efficiently', () => {
  const largeList = Array.from({ length: 10000 }, (_, i) => ({
    amount: i,
    category: 'test'
  }));

  const start = performance.now();
  const total = calculateTotal(largeList);
  const duration = performance.now() - start;

  expect(duration).toBeLessThan(100); // Should complete in <100ms
  expect(total).toBe(49995000);
});

Logic Errors

Use parameterized tests to catch edge cases:

test.each([
  // [input, expected, description]
  [[10, 20, 30], 60, 'normal positive values'],
  [[0, 0, 0], 0, 'all zeros'],
  [[-10, 20, -5], 5, 'mixed positive and negative'],
  [[0.1, 0.2], 0.3, 'decimal precision'],
  [[Number.MAX_SAFE_INTEGER], Number.MAX_SAFE_INTEGER, 'large numbers'],
])('calculateTotal(%p) = %p (%s)', (amounts, expected, description) => {
  const expenses = amounts.map(amount => ({ amount, category: 'test' }));
  expect(calculateTotal(expenses)).toBeCloseTo(expected);
});

4. Test Coverage Analysis

Use automated tools to identify gaps in test coverage.

Finding Untested Code

Run the provided script to identify source files without tests:

python3 scripts/find_untested_code.py src

The script will:

• Scan source directory for all code files
• Identify which files lack corresponding test files
• Categorize untested files by type (components, services, utils, etc.)
• Prioritize files that need testing most

Interpretation:

• API/Services: High priority - test business logic and data operations
• Models: High priority - test data validation and transformations
• Hooks: Medium priority - test stateful behavior
• Components: Medium priority - test complex UI logic
• Utils: Low priority - test as needed for complex functions

Analyzing Coverage Reports

Run the coverage analysis script after generating coverage:

# Generate coverage (using Jest example)
npm test -- --coverage

# Analyze coverage gaps
python3 scripts/analyze_coverage.py coverage/coverage-final.json

The script identifies:

• Files below coverage threshold (default 80%)
• Statement, branch, and function coverage percentages
• Priority files to improve

Coverage targets:

• Critical paths: 90%+ coverage
• Business logic: 85%+ coverage
• UI components: 75%+ coverage
• Utilities: 70%+ coverage

5. Test Maintenance and Quality

Ensure tests remain valuable and maintainable.

Test Code Quality Principles

DRY (Don't Repeat Yourself):

// Extract common setup
function createTestExpense(overrides = {}) {
  return {
    amount: 50,
    category: 'food',
    description: 'Test expense',
    date: new Date('2024-01-01'),
    ...overrides
  };
}

test('filters by category', () => {
  const expenses = [
    createTestExpense({ category: 'food' }),
    createTestExpense({ category: 'transport' }),
  ];
  // ...
});

Clear test data:

// Bad: Magic numbers
expect(calculateDiscount(100, 0.15)).toBe(85);

// Good: Named constants
const ORIGINAL_PRICE = 100;
const DISCOUNT_RATE = 0.15;
const EXPECTED_PRICE = 85;
expect(calculateDiscount(ORIGINAL_PRICE, DISCOUNT_RATE)).toBe(EXPECTED_PRICE);

Avoid test interdependence:

// Bad: Tests depend on execution order
let sharedState;
test('test 1', () => {
  sharedState = { value: 1 };
});
test('test 2', () => {
  expect(sharedState.value).toBe(1); // Depends on test 1
});

// Good: Independent tests
test('test 1', () => {
  const state = { value: 1 };
  expect(state.value).toBe(1);
});
test('test 2', () => {
  const state = { value: 1 };
  expect(state.value).toBe(1);
});

Workflow Decision Tree

Follow this decision tree to determine the testing approach:

1. Adding new functionality?

   • Yes → Write tests first (TDD)
     • Write failing test
     • Implement feature
     • Verify test passes
     • Refactor
   • No → Go to step 2

2. Fixing a bug?

   • Yes → Apply bug analysis process
     • Reproduce the bug
     • Write failing test demonstrating bug
     • Fix the implementation
     • Verify test passes
   • No → Go to step 3

3. Improving test coverage?

   • Yes → Use coverage tools
     • Run find_untested_code.py to identify gaps
     • Run analyze_coverage.py on coverage reports
     • Prioritize critical paths
     • Write tests for untested code
   • No → Go to step 4

4. Analyzing code quality?

   • Yes → Systematic review
     • Check for security vulnerabilities
     • Test edge cases and error handling
     • Verify performance characteristics
     • Review error handling

Testing Frameworks and Tools

Recommended Stack

Unit/Integration Testing:

• Jest or Vitest for test runner
• Testing Library for React components
• Supertest for API testing
• MSW (Mock Service Worker) for API mocking

E2E Testing:

• Playwright or Cypress
• Page Object Model pattern

Coverage:

• Istanbul (built into Jest/Vitest)
• Coverage reports in JSON format

Running Tests

# Run all tests
npm test

# Run with coverage
npm test -- --coverage

# Run specific test file
npm test -- ExpenseCalculator.test.ts

# Run in watch mode
npm test -- --watch

# Run E2E tests
npm run test:e2e

Reference Documentation

For detailed patterns and techniques, refer to:

• references/testing_patterns.md - Comprehensive testing patterns, best practices, and code examples
• references/bug_analysis.md - In-depth bug analysis framework, common bug patterns, and debugging techniques

These references contain extensive examples and advanced techniques. Load them when:

• Dealing with complex testing scenarios
• Need specific pattern implementations
• Debugging unusual issues
• Seeking best practices for specific situations

Scripts

analyze_coverage.py

Analyze Jest/Istanbul coverage reports to identify gaps:

python3 scripts/analyze_coverage.py [coverage-file]

Automatically finds common coverage file locations if not specified.

Output:

• Files below coverage threshold
• Statement, branch, and function coverage percentages
• Priority files to improve

find_untested_code.py

Find source files without corresponding test files:

python3 scripts/find_untested_code.py [src-dir] [--pattern test|spec]

Output:

• Total source and test file counts
• Test file coverage percentage
• Untested files categorized by type (API, services, components, etc.)
• Recommendations for prioritization

Best Practices Summary

1. Write tests first (TDD) when adding new features
2. Test behavior, not implementation - tests should survive refactoring
3. Keep tests independent - no shared state between tests
4. Use descriptive names - test names should explain the scenario
5. Cover edge cases - null, empty, boundary values, error conditions
6. Mock external dependencies - tests should be fast and reliable
7. Maintain high coverage - 80%+ for critical code
8. Fix failing tests immediately - never commit broken tests
9. Refactor tests - apply same quality standards as production code
10. Use tools - automate coverage analysis and gap identification