betting-brain-v3 / rules

---
version: "1.0.0"
alwaysApply: true
description: "AI-friendly testing patterns and Bun test integration"
lastUpdated: "2025-10-08"
dependencies: ["quality-standards", "testing-patterns", "bun-runtime"]
---

# AI-Friendly Testing Patterns

## Bun Test with AI Integration

**Always use AI-friendly test output when working with AI assistants:**

```bash
# Dedicated AI command (preferred)
bun run test:ai

# Environment variable approach
CLAUDECODE=1 bun test
CLAUDECODE=1 bun test tests/unit
CLAUDECODE=1 bun test --coverage
```

## Auto-Detection

**CI scripts automatically detect AI environments:**
- `CLAUDECODE=1` - Claude Code
- `REPL_ID=1` - Replit AI  
- `AGENT=1` - Generic AI agent

**Commands that auto-enable quiet mode:**
```bash
bun run ci:local    # ✅ Auto-detects AI environment
bun run ci:bun      # ✅ Auto-detects AI environment
```

## Benefits

- ✅ Shows only test failures (not passing tests)
- ✅ Reduces output verbosity for AI context windows
- ✅ Preserves failure details and summaries
- ✅ Improves readability in AI sessions

## Test Mock Patterns

**For D1 database mocks, handle both regular and cost cap queries:**

```typescript
mockEnv = {
  ANALYTICS: {
    prepare: (query: string) => {
      // Handle cost cap queries (dbstat)
      if (query.includes('dbstat') || query.includes('SUM(pgsize)')) {
        return {
          first: async () => ({ size: 1000000, rows: 1000 }),
          bind: () => ({ first: async () => ({ size: 1000000, rows: 1000 }) }),
          run: async () => ({ success: true }),
          all: async () => []
        };
      }
      
      // Handle regular queries
      return {
        bind: (...params: any[]) => ({
          first: async () => ({ /* your data */ })
        }),
        first: async () => null,
        run: async () => ({ success: true }),
        all: async () => []
      };
    }
  }
};
```

## Environment Variables

Set any of these to enable quiet mode:

| Variable | Use Case |
|---|---|
| `CLAUDECODE=1` | Claude Code sessions |
| `REPL_ID=1` | Replit AI environments |
| `AGENT=1` | Generic AI agent flag |

## Package Scripts

Available in `package.json`:

```json
{
  "scripts": {
    "test:ai": "CLAUDECODE=1 bun test",
    "test": "bun test",
    "test:unit": "bun test tests/unit",
    "test:integration": "bun test tests/integration"
  }
}
```

## Behavior Examples

### Normal Output (Verbose)
```bash
$ bun test
✓ CLV Calculations > should calculate positive CLV [2.67ms]
✓ CLV Calculations > should trigger alert when CLV < -2% [0.39ms]
✓ CLV Calculations > should handle customer with no data [0.44ms]
✓ CLV Calculations > should validate customer ID format [0.19ms]
✓ CLV Calculations > should respect cost cap limits [0.06ms]
 5 pass
 0 fail
```

### AI-Friendly Output (Quiet)
```bash
$ CLAUDECODE=1 bun test
# Only shows if there are failures:
✗ getSharpScore > returns score for events [2.15ms]
  Expected: 75
  Received: 0
 7 pass
 1 fail
```

## Integration

### CI Scripts

Both CI scripts auto-detect AI environments:

#### `scripts/bun-ci.ts`

```typescript
private isAIEnvironment(): boolean {
  return !!(
    process.env.CLAUDECODE || 
    process.env.REPL_ID || 
    process.env.AGENT
  );
}

private async runTests(): Promise<boolean> {
  if (this.isAIEnvironment()) {
    console.log('  🤖 AI environment detected - enabling quiet mode');
    process.env.CLAUDECODE = '1';
  }
  
  return await this.runStep('Tests', 'bun', ['test', '--concurrent']);
}
```

#### `scripts/ci-local.ts`

```typescript
async run(): Promise<boolean> {
  // Enable AI-friendly output if in AI environment
  if (this.isAIEnvironment()) {
    console.log('🤖 AI Environment: Quiet test output enabled');
    process.env.CLAUDECODE = '1';
  }
  
  // ... rest of pipeline
}
```

## Use Cases

### 1. Claude Code Sessions

When using Cursor with Claude Code, tests automatically run in quiet mode:

```bash
# In your AI session
$ bun run ci:local
🤖 AI Environment: Quiet test output enabled
# Only failures shown
```

### 2. Replit AI

For Replit-based development:

```bash
# Automatically detected via REPL_ID
$ bun test
# Quiet output automatically enabled
```

### 3. Generic AI Agents

For other AI coding assistants:

```bash
# Set generic flag
export AGENT=1
bun test
```

## Benefits

### For AI Context Windows

| Feature | Without AI Mode | With AI Mode |
|---|---|---|
| Token usage per test run | ~5,000 tokens | ~500 tokens |
| Context efficiency | Low | High |
| Failure visibility | Buried in output | Prominent |
| Summary clarity | Mixed with noise | Clean |

### For Developers

- ✅ **Less scrolling** - Only failures need attention
- ✅ **Faster debugging** - Jump straight to errors
- ✅ **Better focus** - No distraction from passing tests
- ✅ **Clean logs** - Ideal for CI/CD environments

## Testing the Feature

### Verify Auto-Detection

```bash
# Set AI environment
export CLAUDECODE=1

# Run CI - should show detection message
bun run ci:local

# Expected output:
# 🤖 AI Environment: Quiet test output enabled
```

### Compare Outputs

```bash
# Normal output
bun test tests/unit/clv.test.ts

# AI-friendly output
CLAUDECODE=1 bun test tests/unit/clv.test.ts
```

### Force Disable

```bash
# Even in AI environment, disable by unsetting
unset CLAUDECODE
unset REPL_ID
unset AGENT

bun test  # Normal verbose output
```

## Related Files

- **[package.json](../../package.json)** - Test scripts
- **[bun-ci.ts](../../scripts/bun-ci.ts)** - CI integration with auto-detection
- **[ci-local.ts](../../scripts/ci-local.ts)** - Local CI with auto-detection
- **[TESTING_STATUS.md](../../docs/TESTING_STATUS.md)** - Overall test status
- **[TESTING_GUIDE.md](../../docs/guides/TESTING_GUIDE.md)** - Complete testing guide
- **[AI_FRIENDLY_TESTING.md](../../docs/testing/AI_FRIENDLY_TESTING.md)** - Detailed guide

## Troubleshooting

### Issue: Quiet mode not activating

**Check environment variables:**
```bash
echo $CLAUDECODE
echo $REPL_ID
echo $AGENT
```

**Solution:**
```bash
# Manually set
export CLAUDECODE=1

# Or use dedicated command
bun run test:ai
```

### Issue: Still seeing verbose output

**Check if running through CI:**
```bash
# CI scripts should auto-detect
bun run ci:local   # ✅ Auto-detects
bun test           # ❌ Needs manual env var
```

**Solution:**
```bash
# Use CI commands or set env var
CLAUDECODE=1 bun test
```

### Issue: Want verbose output in AI session

**Temporarily disable:**
```bash
# Unset variables
unset CLAUDECODE
unset REPL_ID
unset AGENT

# Run tests
bun test
```

## Best Practices

### ✅ Do

- Use `bun run test:ai` for explicit AI mode
- Let CI scripts auto-detect environment
- Use quiet mode in AI pair programming sessions
- Document expected test behavior for AI context

### ❌ Don't

- Manually parse test output in scripts (use exit codes)
- Assume quiet mode hides all information (failures are shown)
- Set AI env vars in production (CI only)
- Forget to check logs when tests pass (summary is shown)

## Future Enhancements

Potential improvements being considered:

- [ ] Custom quiet mode levels (minimal, standard, verbose)
- [ ] AI-friendly coverage reports
- [ ] Structured JSON output for AI parsing
- [ ] Integration with GitHub Copilot
- [ ] Smart failure grouping for AI context

## References

- **[Bun Test Documentation](https://bun.sh/docs/cli/test)** - Official Bun test docs
- **[Cursor Rules](.cursor/rules/testing-patterns.mdc)** - Testing patterns
- **[CI/CD Guide](../../docs/guides/CI_CD_GUIDE.md)** - Continuous integration

version: "1.0.0"
lastUpdated: "2025-10-08"
dependencies: ["quality-standards", "testing-patterns", "bun-runtime"]
---

**Status:** Production-Ready ✅  
**Maintenance:** Automated via CI  
**Support:** Check [TESTING_STATUS.md](../../docs/TESTING_STATUS.md) for issues