build-update-tests

name	build-update-tests
description	Evaluate existing test coverage, identify gaps and pattern violations, then create or update comprehensive tests. Use when user says "build tests", "update tests", "test [component]", "add test coverage", or "check test coverage".
allowed-tools	Read, Write, Edit, Glob, Grep, Bash
version	3.2.0

Build/Update Tests Skill

Evaluate test coverage and create or update tests when gaps or pattern violations are identified.

<when_to_use>

When to Use

Invoke when user says:

• "build tests for [file]"
• "update tests for [file]"
• "test [component/service/hook]"
• "add test coverage for [file]"
• "check test coverage" </when_to_use>

## Workflow Overview

Phase	Action	Reference
1	Code Analysis & Risk Assessment	execution-phases.md
2	Existing Test Discovery & Pattern Compliance	execution-phases.md
3	Test Design	execution-phases.md
4	Test Implementation	execution-phases.md
5	Validation	execution-phases.md
6	Reporting	report-template.md

For detailed phase instructions: references/execution-phases.md

<risk_matrix>

Risk Matrix

Risk Level	Characteristics	Required Tests
High	Business logic, mutations, forms, auth, payments	Unit + Integration + E2E
Medium	Data fetching, filtering, validation, hooks	Unit + Integration OR Unit + E2E
Low	Pure utilities, formatters, type guards	Unit only

Code Type Requirements

Code Type	Required Tests
User-facing component	Unit + E2E
Form component	Unit + E2E
Service with mutations	Unit + Integration + E2E
Service read-only (simple)	Unit
Service read-only (complex)	Unit + Integration
Pure utility	Unit
React hook (simple)	Unit
React hook (complex)	Unit + Integration
Page component	E2E

</risk_matrix>

<test_locations>

Test File Locations

Level	Pattern	Example
Unit	src/**/__tests__/[name].test.{ts,tsx}	src/components/__tests__/SessionForm.test.tsx
Integration	src/**/*.integration.test.{ts,tsx}	src/services/__tests__/email.integration.test.ts
E2E	playwright/tests/*.spec.ts	playwright/tests/session-creation.spec.ts

</test_locations>

<pattern_compliance>

Pattern Compliance

Check these pattern documents before writing tests:

• claude-patterns/testing-patterns.md (React component unit tests)
• claude-patterns/vitest-testing-patterns.md (Service/utility unit tests)
• claude-patterns/playwright-best-practices.md (E2E tests)

Priority Order

Priority	Type	Examples
P0 (Must Fix)	Safety & Correctness	No direct DB inserts in E2E, proper async handling, worker validation
P1 (Should Fix)	Maintainability	test.step() usage, proper cleanup, comprehensive assertions
P2 (Nice to Have)	Best Practices	Naming conventions, organization, comments

Fix P0 violations before creating new tests—a test that violates patterns is worse than no test.

For detailed patterns: references/best-practices.md </pattern_compliance>

## Invocation

Basic:

Use build-update-tests skill for src/components/MyComponent.tsx

With requirements:

Use build-update-tests for src/services/email.service.ts with critical flows from docs/email-requirements.md

## Commands

# Run unit tests for specific file
npm run test:unit -- [test-file-name]

# Run all unit tests
npm run test:unit

# Run E2E tests
npx playwright test [spec-file]

## Output

Produce a comprehensive report using references/report-template.md:

1. Evaluation Phase: Risk assessment, test discovery, pattern compliance, gap analysis
2. Implementation Phase: Actions taken, tests created/updated, coverage achieved
3. Summary: Strengths, warnings, gaps fixed, recommendations

<approval_gates>

Approval Gates

Gate	Phase	Question
None	-	This skill runs autonomously without user approval gates

Note: Test creation is non-destructive. User reviews output report and decides what to keep. </approval_gates>

<safety_rules>

Safety Rules

1. Never delete existing passing tests - only add or update
2. Fix P0 pattern violations before creating new tests - bad tests are worse than no tests
3. Preserve existing test structure - don't reorganize without clear benefit </safety_rules>

## Limitations

• Cannot create E2E tests without understanding full user workflow
• Cannot determine test priority without requirements documentation
• Complex mocking may require code refactoring for testability

<quick_reference>

Quick Reference

# Find existing tests
glob "src/**/__tests__/**/*.test.{ts,tsx}"
glob "playwright/tests/*.spec.ts"

# Check for pattern docs
cat claude-patterns/testing-patterns.md
cat claude-patterns/playwright-best-practices.md

</quick_reference>

## References

• references/execution-phases.md - Detailed 6-phase workflow
• references/report-template.md - Output report format
• references/best-practices.md - Testing patterns and examples

<version_history>

Version History

• v3.2.0 (2025-01-18): AI optimization updates

  • Add blockquote summary after title
  • Soften directive language per Opus 4.5 guidance

• v3.1.0 (2025-12-28): Added missing sections per skill-authoring-patterns audit

  • Added trigger phrases to frontmatter description
  • Added <approval_gates> section
  • Added <safety_rules> section
  • Added <references> section

• v3.0.0 (2025-12-28): Refactored to follow skill-authoring-patterns

  • Reduced from 850 to ~180 lines
  • Created references/: execution-phases.md, report-template.md, best-practices.md
  • Added XML tags for structure
  • Converted to imperative writing style

• v2.0.0 (2025-11-15): Combined audit and implementation workflows

• v1.0.0 (2025-10-01): Initial release </version_history>