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

```bash
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:

```bash
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:
```typescript
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
```markdown
## 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
```markdown
## 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
```