| name | run-tests |
| description | Automatically invoked when running tests, analyzing test results, or verifying code changes. Ensures tests are run appropriately and results are interpreted correctly. |
Run Tests Skill
This skill activates when you need to run tests, analyze test output, or verify code changes.
When This Skill Activates
Automatically engage when:
- Implementing or modifying code
- Fixing bugs
- Completing a feature
- Before committing changes
- Investigating test failures
- Validating refactoring
- After dependency updates
Test Running Principles
Run Appropriate Test Level
- Unit tests - During development, after each change
- Integration tests - After unit tests pass, before committing
- E2E tests - Before merging, for critical flows
- Full suite - Before release, in CI/CD
Interpret Results Correctly
- Understand failure root causes
- Distinguish test failures from code failures
- Identify flaky tests
- Recognize false positives/negatives
Fix Failures Systematically
- One failure at a time
- Fix tests that reveal real bugs first
- Update tests that are outdated
- Remove tests that are no longer valuable
Test Commands Reference
Common Test Commands
npm test
yarn test
pytest
cargo test
npm test path/to/test.spec.js
pytest tests/test_user.py
cargo test user_tests
npm test -- --grep "user"
pytest -k "user"
cargo test user
npm test -- --coverage
pytest --cov=src tests/
cargo test --coverage
npm test -- --watch
pytest --watch
cargo watch -x test
npm test -- --only-failures
pytest --lf
Test Running Workflow
1. Identify What to Test
Changed a function? Run unit tests for that function
npm test user.service.spec.js
Changed an API endpoint? Run integration tests
npm test -- --grep "POST /api/users"
Changed UI component? Run component tests
npm test UserProfile.test.jsx
Fixed a bug? Run tests that cover that code path
Refactored? Run full test suite
2. Run Tests
Execute appropriate test command from project root
3. Analyze Results
Success ✓
PASS tests/user.service.spec.js
UserService
✓ creates user with valid data (15ms)
✓ throws error for invalid email (8ms)
✓ throws error for duplicate email (12ms)
Test Suites: 1 passed, 1 total
Tests: 3 passed, 3 total
Time: 2.145s
Action: Proceed with confidence
Failure ✗
FAIL tests/user.service.spec.js
UserService
✓ creates user with valid data (15ms)
✗ throws error for invalid email (23ms)
✓ throws error for duplicate email (12ms)
● UserService › throws error for invalid email
expect(received).toThrow(expected)
Expected: "Invalid email"
Received: function did not throw
18 | it('throws error for invalid email', () => {
19 | const invalidUser = { email: 'invalid', name: 'Test' }
> 20 | expect(() => createUser(invalidUser)).toThrow('Invalid email')
| ^
21 | })
Action: Investigate and fix
4. Investigate Failures
Read Error Message
- What was expected?
- What was received?
- What line failed?
Check Code
- Is the test correct?
- Is the code correct?
- Is there a race condition?
- Is test data stale?
Reproduce Locally
- Run test in isolation
- Run with debugger
- Add console.logs
- Check test assumptions
5. Fix Issues
Code Bug
Fix the code, then re-run tests
Test Bug
Fix the test, then re-run
Flaky Test
- Identify timing issues
- Add proper async handling
- Mock time-dependent functions
- Increase timeouts cautiously
Outdated Test
Update test to match new requirements
6. Verify Fix
Re-run tests to confirm they pass
7. Run Broader Tests
After local tests pass, run:
- Related tests
- Full test suite
- Integration tests
- E2E tests (if applicable)
Test Output Interpretation
All Pass
Test Suites: 5 passed, 5 total
Tests: 47 passed, 47 total
Meaning: All tests executed successfully
Action: Proceed with commit/deployment
Some Fail
Test Suites: 3 failed, 2 passed, 5 total
Tests: 12 failed, 35 passed, 47 total
Meaning: Code changes broke existing functionality
Action: Investigate and fix failures before proceeding
Test Errors
Error: Cannot find module 'some-module'
Meaning: Test setup or dependency issue
Action: Check dependencies, run npm install
Timeout
Timeout - Async callback was not invoked within timeout
Meaning: Async operation didn't complete
Action: Check async handling, increase timeout if legitimate
Coverage Report
File | % Stmts | % Branch | % Funcs | % Lines |
---------------|---------|----------|---------|---------|
user.service.js| 85.71 | 75.00 | 83.33 | 85.71 |
All files | 85.71 | 75.00 | 83.33 | 85.71 |
Meaning: Percentage of code covered by tests
Action: Review uncovered lines, add tests for critical paths
Test Types and When to Run
Unit Tests
What: Individual functions, methods, classes
When: During development, after each code change
Speed: Very fast (< 1 second)
Command: npm test path/to/unit.test.js
Integration Tests
What: Component interactions, API endpoints, database operations
When: After unit tests pass, before committing
Speed: Fast to moderate (seconds)
Command: npm test:integration or similar
E2E Tests
What: Complete user flows, critical business processes
When: Before merging, before deployment
Speed: Slow (minutes)
Command: npm test:e2e or similar
Smoke Tests
What: Basic functionality checks
When: After deployment, after major changes
Speed: Fast
Command: npm test:smoke or similar
Coverage Analysis
Running Coverage
npm test -- --coverage
Understanding Coverage
- Statements: % of executable statements run
- Branches: % of if/else branches taken
- Functions: % of functions called
- Lines: % of lines executed
Coverage Targets
- Critical paths: 90%+
- Business logic: 80%+
- Utilities: 80%+
- Overall: 70-80%
Coverage Gaps
-----------------|---------|----------|---------|---------|
File | % Stmts | % Branch | % Funcs | % Lines |
-----------------|---------|----------|---------|---------|
user.service.js | 85.71 | 50.00 | 83.33 | 85.71 | 45-47
Uncovered lines: 45-47
Action: Review those lines, add tests if critical
Debugging Test Failures
Run Single Test
npm test -- --testNamePattern="creates user"
Run with Verbose Output
npm test -- --verbose
Add Debug Statements
it('creates user', () => {
console.log('Input:', userData)
const result = createUser(userData)
console.log('Result:', result)
expect(result.id).toBeDefined()
})
Use Debugger
it('creates user', () => {
debugger;
const result = createUser(userData)
expect(result.id).toBeDefined()
})
Check Test Isolation
npm test user.spec.js
npm test
If it passes alone but fails with others → test interdependence issue
Common Test Issues
Flaky Tests
Symptom: Sometimes pass, sometimes fail
Causes:
- Timing/race conditions
- Shared state between tests
- External dependencies
- Random data
Solutions:
- Proper async/await usage
- Reset state between tests
- Mock external dependencies
- Use deterministic test data
Slow Tests
Symptom: Tests take too long
Causes:
- Too many E2E tests
- Not using mocks
- Database operations
- Network requests
Solutions:
- Mock external dependencies
- Use test doubles
- Optimize test setup
- Run critical tests only during development
False Positives
Symptom: Tests pass but code is broken
Causes:
- Testing implementation not behavior
- Insufficient assertions
- Mock returning incorrect data
Solutions:
- Test observable behavior
- Add specific assertions
- Verify mock data matches reality
False Negatives
Symptom: Tests fail but code is correct
Causes:
- Outdated tests
- Overly strict assertions
- Test environment issues
Solutions:
- Update tests to match requirements
- Relax overly specific assertions
- Fix test environment
Test Maintenance
After Fixing Bug
- Add test that would have caught the bug
- Verify test fails without fix
- Verify test passes with fix
After Refactoring
- Run full test suite
- All tests should still pass
- If tests need updates, update them
- Coverage should remain same or improve
After Changing Requirements
- Update tests to match new requirements
- Remove tests for removed features
- Add tests for new functionality
Regular Maintenance
- Remove flaky tests or fix them
- Update outdated tests
- Remove redundant tests
- Improve slow tests
Best Practices
Run Tests Before Committing
npm test && git commit -m "message"
Use Watch Mode During Development
npm test -- --watch
Fix Tests Immediately
Don't let broken tests linger
Trust Your Tests
If tests pass, code is likely correct
If tests fail, investigate immediately
Keep Tests Fast
Fast tests = run frequently = catch bugs early
Integration with Development Workflow
Before Starting Work
git pull
npm install
npm test
During Development
npm test -- --watch
Before Committing
npm test
npm test -- --coverage
git add .
git commit -m "message"
Before Pushing
npm test
git push
CI/CD Integration
Tests should run automatically in CI/CD:
- On every push
- On every pull request
- Before deployment
Check CI/CD status before merging or deploying
References
- Test framework documentation: Check project's testing framework
- Coverage tools: Jest, NYC, Coverage.py, Tarpaulin
- Testing best practices: See
ai_docs/knowledge/testing/
Constraints
- Don't skip tests to save time
- Don't ignore test failures
- Don't commit broken tests
- Don't over-mock - test real behavior when possible
- Keep tests maintainable and readable