feat: Add functional health checks for test prerequisites (#65)

Replaces basic "service is up" checks with functional verification that tests can actually use the services. ## Changes ### New Health Checks - **RPC Proxy**: Verifies eth_call works and deployed contracts are accessible - **GraphQL**: Confirms Ponder has indexed data with non-zero stats - **Web App**: Validates endpoint accessibility ### Improvements - Clear error messages explain what failed and how to fix it - Checks verify actual functionality, not just HTTP 200 responses - Fails fast before tests run with cryptic errors ### Files - `tests/setup/health-checks.ts` - Core health check functions - `tests/setup/stack.ts` - Integration with waitForStackReady() - `tests/HEALTH_CHECKS.md` - Documentation and troubleshooting guide ## Error Message Example Before: ``` RPC health check failed with status 404 ``` After: ``` ❌ 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. 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 ``` ## Benefits - ✅ Tests fail fast with clear error messages - ✅ Catches configuration issues before tests run - ✅ Verifies services are actually usable, not just running resolves #61 Co-authored-by: johba <johba@harb.eth> Reviewed-on: https://codeberg.org/johba/harb/pulls/65
2025-10-05 20:03:07 +02:00 · 2025-10-05 20:03:07 +02:00 · b1f40374cd
commit b1f40374cd
parent 1645865c5a
3 changed files with 472 additions and 42 deletions
--- a/tests/HEALTH_CHECKS.md
+++ b/tests/HEALTH_CHECKS.md
@ -0,0 +1,133 @@
+# 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}}"}'
+   ```