Running Tests

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

Unit Tests

crawbl test unit

Runs all Go unit tests across the codebase. No infrastructure required — external dependencies are mocked.

End-to-End Tests

E2E tests use Cucumber/godog with Gherkin feature files. They run against a live orchestrator API and exercise the full request lifecycle.

Flags

Flag	Default	Description
--base-url	http://localhost:7171	Orchestrator base URL
--e2e-token	$CRAWBL_E2E_TOKEN	Gateway auth bypass token
--verbose, -v	false	Pretty-printed Gherkin output
--timeout	60s	HTTP request timeout
--runtime-ready-timeout	3m	Wait for workspace runtime readiness
--runtime-poll-interval	2s	Runtime readiness poll frequency
--database-dsn	$CRAWBL_E2E_DATABASE_DSN	Postgres DSN for DB assertions
--category, -c	(all)	Run only tests from a subfolder (e.g. chat, tools, auth)
--port-forward	false	Auto-start kubectl port-forwards

Running locally

Easiest — let crawbl manage the port-forwards:

crawbl test e2e --port-forward --verbose

Manual — port-forward yourself first:

kubectl port-forward svc/orchestrator 7171:7171 -n backend &
kubectl port-forward svc/backend-postgresql 5432:5432 -n backend &

crawbl test e2e \
  --base-url http://localhost:7171 \
  --database-dsn "postgres://postgres:<PG_PASSWORD>@localhost:5432/crawbl?sslmode=disable&search_path=orchestrator" \
  --runtime-ready-timeout 4m \
  --verbose

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

Running by category

Run only a subset of tests using --category (matches a subfolder name under the feature files directory):

crawbl test e2e --port-forward --category chat --verbose
crawbl test e2e --port-forward --category auth --verbose
crawbl test e2e --port-forward --category tools --verbose

Running against the dev cluster

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

Source CRAWBL_E2E_TOKEN from your .env file:

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

CI (GitHub Actions)

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

1

Step 1

Configure cluster access

CI saves the dev cluster kubeconfig via doctl kubernetes cluster kubeconfig save crawbl-dev.

2

Step 2

Wait for rollout

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

3

Step 3

Run E2E

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

You do not need to run E2E tests manually before pushing — CI runs them automatically. Run locally against a port-forward when debugging failures or developing new scenarios.

Full Verification

crawbl dev verify

Runs in order: fmt (formatting) → lint (golangci-lint) → test (unit tests). Use this before pushing.

Pre-Push Hook

./crawbl setup installs a repo-managed pre-push hook that runs:

./crawbl ci check

This builds the local CLI, runs unit tests, and compiles the linux/amd64 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 test e2e --port-forward -v	E2E with auto port-forward, verbose output
crawbl test e2e --port-forward -c chat -v	E2E for a single category
crawbl test e2e --base-url <url> --e2e-token $TOKEN -v	E2E against any remote endpoint
crawbl dev verify	Format + lint + unit tests
./crawbl ci check	Pre-push gate: build + unit tests + linux/amd64 binary
crawbl dev lint --fix	Auto-fix lint issues

---

What's next: Writing E2E Scenarios