bitspire/.claude/skills/test.md

/test - Testing Agent

Purpose

Run tests, analyze coverage, generate test cases, and validate ATM transaction flows.

Invocation

/test [command] [target]

Commands:

• run - Run tests (default)
• coverage - Run with coverage report
• generate - Generate test cases for a file
• flow - Validate transaction flow
• hardware - Run hardware mock tests

Test Categories

1. Unit Tests

Location: *.test.ts or *.spec.ts alongside source files

pnpm test                    # All tests
pnpm test --filter @bitSpire/nostr-client  # Specific package

2. Integration Tests

Location: tests/integration/

Tests cross-package interactions:

• Nostr client + CLINK
• State machine + Hardware mocks
• Lightning client + Invoice handling

3. E2E Tests (Playwright)

Location: tests/e2e/

Full transaction flows:

• Cash-in flow (bill insert → Lightning payment)
• Cash-out flow (Lightning receive → dispense)
• Error recovery flows

4. Hardware Mock Tests

Test against mock hardware:

pnpm test:hardware           # With mock validator/dispenser
REAL_HARDWARE=true pnpm test:hardware  # With real hardware (CI skip)

Test Generation

For a new file:

/test generate packages/lightning/src/client.ts

Generates test skeleton:

import { describe, it, expect, vi } from 'vitest'
import { LightningPubClient } from './client'

describe('LightningPubClient', () => {
  describe('createInvoice', () => {
    it('should create valid BOLT11 invoice', async () => {
      // TODO: Implement
    })

    it('should handle network errors', async () => {
      // TODO: Implement
    })

    it('should validate amount bounds', async () => {
      // TODO: Implement
    })
  })
})

Test Case Suggestions

Based on code analysis, suggest test cases for:

• Happy path
• Edge cases (null, empty, max values)
• Error conditions
• Timeout scenarios
• Concurrent operations

Transaction Flow Validation

Cash-In Flow

/test flow cash-in

Validates:

1. Idle → Select Cash-In
2. Bill insertion events received
3. Amount calculation correct
4. CLINK offer generated
5. Payment received event
6. Receipt sent (optional)
7. Return to Idle

Cash-Out Flow

/test flow cash-out

Validates:

1. Idle → Select Cash-Out
2. Amount selection
3. Invoice generated
4. Payment received
5. Cash dispensed
6. Bills removed detection (F56)
7. Return to Idle

Error Flows

/test flow errors

Validates:

• Hardware timeout recovery
• Payment failure handling
• Network disconnection
• Partial dispense handling

Coverage Requirements

Minimum Coverage Targets

Package	Statements	Branches	Functions
nostr-client	80%	75%	80%
clink	80%	75%	80%
state-machine	90%	85%	90%
lightning	80%	75%	80%
hal (mocks)	70%	65%	70%

Critical Paths (100% coverage required)

• Payment processing
• Cash dispensing logic
• Key handling
• Amount calculations

Output Format

Test Run

## Test Results: [target]

### Summary
- Total: 42
- Passed: 40
- Failed: 2
- Skipped: 0

### Failed Tests
1. `client.test.ts` > createInvoice > should validate amount
   - Expected: Error thrown
   - Received: Invoice created with negative amount

### Coverage
| File | Statements | Branches | Functions |
|------|------------|----------|-----------|
| client.ts | 85% | 78% | 90% |

Test Generation

## Generated Tests: [file]

### Test File
`packages/lightning/src/client.test.ts`

### Suggested Test Cases
1. **createInvoice**
   - ✅ Valid amount creates invoice
   - ✅ Zero amount rejected
   - ✅ Negative amount rejected
   - ✅ Network error handled

### Missing Coverage
- `payInvoice` has no tests
- Error handling branch at line 45 untested

Example Usage

/test coverage packages/state-machine/

/test generate packages/clink/src/offer.ts

/test flow cash-out