Principle:Helicone Helicone Verification and Testing
| Knowledge Sources | |
|---|---|
| Domains | Local Development, Testing |
| Last Updated | 2026-02-14 00:00 GMT |
Overview
Verification and testing is the practice of confirming that all Helicone services are running correctly after local setup, using health check endpoints and end-to-end test suites.
Description
After completing the local development setup (prerequisites, environment configuration, infrastructure startup, migrations, and application service startup), developers need a systematic way to verify that everything is working. Helicone provides two levels of verification:
Health Check Endpoints: Each service exposes a health check route:
- Jawn:
GET /healthcheckon port 8585 -- returns HTTP 200 with a JSON body containing astatusproperty, implicitly verifying PostgreSQL connectivity. - ClickHouse:
GET /pingon port 18123 -- returns HTTP 200 with bodyOk.\n. - AI Gateway:
GET /healthcheckon port 8793 -- returns HTTP 200. - Worker API:
GET /healthcheckon port 8788 -- returns HTTP 200.
E2E Test Suite: The e2e/ directory contains Jest tests that programmatically verify service health. The health.test.ts file runs health checks against all services with retry logic (3 attempts, 2-second delay), and includes an aggregate test that runs all checks in parallel and reports a summary table.
The test suite uses configurable base URLs via environment variables (AI_GATEWAY_URL, WORKER_API_URL, JAWN_URL, CLICKHOUSE_URL), defaulting to standard local development ports.
Usage
Use health checks as the final step in local setup to confirm everything is working. Use the E2E test suite for automated verification in CI/CD pipelines or after making infrastructure changes.
Theoretical Basis
Health check endpoints follow the "health endpoint monitoring pattern" where each service exposes a lightweight route that exercises its critical dependencies. A healthy Jawn response implicitly confirms PostgreSQL connectivity, while a healthy ClickHouse ping confirms the analytics database is responsive.
The retry pattern in the E2E tests accounts for the startup delay inherent in containerized services -- infrastructure may report as running via Docker before it is fully ready to accept connections.
The test constants in e2e/lib/constants.ts define service URLs, endpoint paths, and test credentials from the local seed data, providing a single source of truth for test configuration.