harb/tests/HEALTH_CHECKS.md

# Functional Health Checks

## Overview

The test suite includes functional health checks that verify services are actually usable, not just running. This prevents cryptic test failures and provides clear error messages when prerequisites aren't met.

## What Gets Checked

### 1. RPC Proxy Functionality
- ✅ Verifies RPC endpoint responds to requests
- ✅ Confirms `eth_chainId` returns valid chain ID
- ✅ Tests contract accessibility via `eth_call` to deployed Kraiken contract
- ✅ Validates deployed contracts from `onchain/deployments-local.json` are accessible

**Why:** Catches RPC proxy misconfigurations (404s), deployment issues, and contract accessibility problems before tests run.

### 2. GraphQL Indexed Data
- ✅ Verifies GraphQL endpoint is responsive
- ✅ Confirms Ponder has indexed contract events
- ✅ Validates stats data contains non-zero values (actual indexed data)

**Why:** Ensures Ponder has completed indexing before tests attempt to query data. Prevents "no data found" errors in tests.

### 3. Web App Accessibility
- ✅ Confirms webapp endpoint returns 200 or 308 status
- ✅ Validates routing is functional

**Why:** Basic check that frontend is accessible for UI tests.

## How It Works

Health checks run automatically in `beforeAll` hooks via `waitForStackReady()`:

```typescript
test.beforeAll(async () => {
  await startStack();
  await waitForStackReady({
    rpcUrl: STACK_RPC_URL,
    webAppUrl: STACK_WEBAPP_URL,
    graphqlUrl: STACK_GRAPHQL_URL,
  });
});
```

The checks poll every 2 seconds with a 3-minute timeout, providing clear feedback if any service fails.

## Error Messages

### Before (Generic)
```
RPC health check failed with status 404
```

### After (Specific)
```
❌ Stack health check failed

Failed services:
  • RPC Proxy: RPC proxy returned HTTP 404
    Expected 200, got 404. Check if Anvil is running and RPC_URL is correct.
  • GraphQL Indexer: GraphQL has no indexed data yet
    Ponder is running but has not indexed contract events. Wait longer or check Ponder logs.

Troubleshooting:
  1. Check stack logs: tail tests/.stack.log
  2. Verify services are running: ./scripts/dev.sh status
  3. Restart stack: ./scripts/dev.sh restart --full
```

## Implementation

### Files
- `tests/setup/health-checks.ts` - Core health check functions
- `tests/setup/stack.ts` - Integration with test lifecycle

### API

```typescript
// Individual checks
const result = await checkRpcFunctional('http://127.0.0.1:8545');
if (!result.success) {
  console.error(`${result.service}: ${result.message}`);
  console.error(result.details);
}

// Run all checks
const results = await runAllHealthChecks({
  rpcUrl: 'http://127.0.0.1:8545',
  webAppUrl: 'http://localhost:5173',
  graphqlUrl: 'http://localhost:42069/graphql',
});

// Format errors
const errorMessage = formatHealthCheckError(results);
```

## Benefits

✅ **Fail Fast** - Tests stop immediately with clear errors instead of cryptic failures
✅ **Clear Diagnostics** - Error messages explain what failed and how to fix it
✅ **Catch Config Issues** - Finds env var problems, proxy misconfigurations, and missing data
✅ **Better DX** - Developers know exactly what's wrong without debugging test code

## Troubleshooting

If health checks fail:

1. **Check stack logs**
   ```bash
   tail -f tests/.stack.log
   ```

2. **Verify services are running**
   ```bash
   ./scripts/dev.sh status
   curl http://127.0.0.1:8545 -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'
   curl http://localhost:42069/graphql -X POST -H "Content-Type: application/json" -d '{"query":"{__typename}"}'
   ```

3. **Restart the stack**
   ```bash
   ./scripts/dev.sh restart --full
   ```

4. **Check deployments**
   ```bash
   cat onchain/deployments-local.json
   ```

5. **Verify Ponder indexing**
   ```bash
   curl -X POST http://localhost:42069/graphql -H "Content-Type: application/json" -d '{"query":"{ stats(id:\"0x01\"){kraikenTotalSupply}}"}'
   ```