Skip to main content
By the end of this guide you have two kinds of test in a Forge Go API: table-driven tests that call your RPC handlers against a real Postgres, and a unit test of business logic that runs on a generated mock. Both run in the fast tier, with nothing to install and no Docker. Forge projects its database code from your migrations, so the honest test runs those migrations on Postgres. The test harness boots one embedded Postgres per machine and gives each test its own database (how Forge tests work).

Before you begin

  • A Forge Go API with at least one entity, such as the shop project from Add a database table with a CRUD API and pages. This guide uses its catalog service, with products and reviews tables.
  • Go and task on your PATH. Docker is not needed.
  • The project pinned to forge v1.6 or later (reliant forge --version inside the project).
1

Run the tests Forge already wrote

terminal
terminal
That already ran 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
The last case is the reason to test on Postgres. A mocked store would accept the review; Postgres rejects it with the foreign key, and the handler returns 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:
terminal
Declare the method and the dependency in contract.go, and add the dependency to Deps in service.go:
internal/pricing/contract.go
internal/pricing/service.go
Then run 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 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
This replaces the scaffolded contract_test.go, which skips until it has cases.
5

Run them and check they ran

terminal
terminal
Every case is listed as its own subtest. Run the fast tier again without changes and the unchanged packages print (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. NewTestCatalogServer in the generated helpers_gen_test.go serves 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

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.
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.