Running Tests

This guide covers all the ways to run Crawbl's test suite — locally, against the dev cluster, and in CI.

Unit Tests

Run unit tests with:

./crawbl test unit

This executes all Go unit tests across the codebase. Unit tests mock external dependencies (repos, clients) and run without any infrastructure.

End-to-End Tests

E2E tests use Cucumber/godog with Gherkin feature files. They run against a live API (local or remote) and exercise the full request lifecycle.

Local (Port-Forward)

Forward the orchestrator service to your machine and run:

kubectl port-forward svc/orchestrator 7171:7171 -n backend
./crawbl test e2e --base-url http://localhost:7171

With Database Assertions

Add --database-dsn to verify database state directly after API calls:

kubectl port-forward -n backend svc/backend-postgresql 5432:5432

./crawbl test e2e --base-url http://localhost:7171 \
  --database-dsn "postgres://crawbl:password@localhost:5432/crawbl?sslmode=disable&search_path=orchestrator"

This enables step definitions in steps_db.go that query the database to assert rows were created, updated, or deleted correctly.

Verbose Output

Add -v for pretty-printed Gherkin output showing each step's pass/fail status:

./crawbl test e2e --base-url http://localhost:7171 -v

Remote (Dev Gateway)

Run against the public dev endpoint using the E2E auth bypass token:

./crawbl test e2e --base-url https://dev.api.crawbl.com --e2e-token $CRAWBL_E2E_TOKEN

The token is stored in AWS Secrets Manager and synced to the cluster via ESO. Source it from your .env file:

set -a && source .env && set +a

Verbose Output

Add -v for pretty-printed Gherkin output showing each step's pass/fail status:

./crawbl test e2e --base-url https://dev.api.crawbl.com --e2e-token $TOKEN -v

CI (GitHub Actions)

E2E tests run automatically on every push to main as part of deploy-dev.yml.

1

Step 1

Download the binary

The test job pulls the pre-built crawbl binary from the build job, so it does not need a Go toolchain.

2

Step 2

Configure cluster access

CI runs doctl kubernetes cluster kubeconfig save crawbl-dev so kubectl can reach the dev cluster.

3

Step 3

Wait for rollout

The job waits until the new orchestrator image is live before it starts the E2E suite.

4

Step 4

Run E2E

CI executes ./crawbl test e2e --base-url https://dev.api.crawbl.com --e2e-token $TOKEN -v.

Total CI pipeline time including build, deploy, and tests: approximately 5 minutes.

You do not need to run E2E tests manually before pushing. CI runs them for you. However, running tests locally against a port-forward is useful for debugging failures or developing new scenarios.

Full Verification

Run the full manual local verification pass:

./crawbl dev verify

This executes in order: fmt (formatting) -> lint (golangci-lint) -> test (unit tests). Use this before pushing to catch issues locally.

Pre-Push Hook

The backend repo also installs a repo-managed pre-push hook when you run make setup.

That hook runs:

make ci-check

make ci-check is the lightweight push gate. It builds the local CLI, runs ./crawbl test unit, and compiles the linux/amd64 crawbl binary used in CI. It does not run the live E2E suite.

Quick Reference

Command	What it does
./crawbl test unit	Unit tests only
./crawbl dev verify	Format + lint + unit tests
make ci-check	Pre-push gate: build + unit tests + linux/amd64 binary build
./crawbl test e2e	E2E tests against local Docker Compose stack
./crawbl test e2e --base-url <url>	E2E tests against any endpoint
./crawbl test e2e ... -v	E2E with verbose Gherkin output
./crawbl dev lint --fix	Auto-fix lint issues

---

What's next: Writing E2E Scenarios