Before you begin
- A Forge Go API with at least one entity, such as the
shopproject from Add a database table with a CRUD API and pages. This guide uses itscatalogservice, withproductsandreviewstables. - Go and
taskon yourPATH. Docker is not needed. - The project pinned to forge v1.6 or later (
reliant forge --versioninside the project).
1
Run the tests Forge already wrote
terminal
terminal
TestCRUD_Product_Lifecycle from handlers_crud_test.go against a real Postgres, downloaded and started on first use. The lifecycle test covers the service’s first entity only, and it replays every migration into a fresh database per test. The tests you write next use the faster path.2
Write a table test for your handlers
NewMigratedTestDB gives a test a copy of a template database that has your migrations applied once. NewProduct inserts a valid row derived from the schema. tdd.TableRPC runs one subtest per case against the handler.internal/handlers/catalog/catalog_table_test.go
failed_precondition: create review: a referenced record is missing or still in use (constraint reviews_product_id_fkey). AuthedContext signs the call in as a test user, because the test calls the handler directly rather than through the auth middleware.3
Put business logic in a package with a contract
Logic you want to test without a database goes in a package whose dependencies are interfaces:Declare the method and the dependency in Then run
terminal
contract.go, and add the dependency to Deps in service.go:internal/pricing/contract.go
internal/pricing/service.go
reliant forge generate. It rewrites mock_gen.go with a mock for every interface in contract.go, here MockService and MockTaxRates.reliant forge lint reports forge-graph-unreachable for internal/pricing until a service takes pricing.Service in its Deps and something provides TaxRates. That is wiring, not testing: the tests below run either way.4
Test it with the generated mock
Program the mock by setting its This replaces the scaffolded
RateBasisPointsFunc. tdd.TableContract runs each case and compares Want or matches WantErr with errors.Is. The mock records every call, so the last case also checks that a bad price never reached the rate lookup.internal/pricing/contract_test.go
contract_test.go, which skips until it has cases.5
Run them and check they ran
terminal
terminal
(cached). Before you finish, run the full tier on the packages you touched, with the race detector and no cache:terminal
terminal
What this does not do
- It doesn’t test through the network. These tests call handler methods directly, so the auth middleware and interceptors do not run.
NewTestCatalogServerin the generatedhelpers_gen_test.goserves the service over HTTP with a typed client when you need that. - It doesn’t write a lifecycle test for later entities. Only a service’s first entity gets one. Use the factories (
NewReview,NewCreateReviewRequest) in tests like the ones above. - It doesn’t mark slow tests for you. A test that runs a subprocess or takes more than about two seconds calls
testkit.Slow(t, "<why>")first, so it skips under-short(how Forge tests work).
Troubleshooting
tax rate for CA: MockTaxRates.RateBasisPointsFunc not set
tax rate for CA: MockTaxRates.RateBasisPointsFunc not set
A generated mock returns this error from any method you did not program, instead of a zero value. Set
RateBasisPointsFunc (or the …Func field the message names) on the mock before the call.internal: get product failed
internal: get product failed
Every call fails with
internal when the service runs on the default database, which is empty: NewTestCatalog(t) with no WithDB creates no tables. The handler hides the database error from the caller. Pass catalog.WithDB(catalog.NewMigratedTestDB(t)).Next steps
How Forge tests work
The shared Postgres, template copies, the two tiers and why a skipped test never counts as a pass.
Add a database table with a CRUD API and pages
Add the entity whose handlers these tests call.
Contracts and generated mocks
contract.go, Deps and what mock_gen.go holds.Generated vs yours
Which test files Forge regenerates and which you own.