# Glossary — Unit testing (this repo)

The canonical vocabulary. Opinionated: where the repo has a house term, that wins; the general
industry term is noted so you can map to the interview. Adhere to these names in every lesson.

---

### unit test
A test that exercises one unit (a function/method) in isolation, with its collaborators replaced by
**mocks** — no real database, network, or Docker. Here: a `*_test.go` run by `go test ./internal/...`,
using testify mocks from `mock/`. Distinct from BDD/E2E (out of scope — see [scope boundary](#scope-boundary)).

### `go test`
Go's built-in test runner. Runs every `TestXxx(t *testing.T)` in `*_test.go` files that sit next to
the code they test (same package). This repo drives it via `make … unit-test-service`.

### table-driven test
The house (and Go-idiomatic) pattern: enumerate cases, then loop and run each as a **subtest**. In
this repo the "table" is often a sequence of `t.Run("return … when …", …)` blocks rather than a
literal slice — same idea, one sub-test per case.

### subtest (`t.Run`)
A named test-within-a-test: `t.Run("name", func(t *testing.T){ … })`. Gives each case its own name,
pass/fail line, and (optionally) parallelism. The unit of a table-driven test.

### `t.Parallel()`
Marks a test (or subtest) to run concurrently with other parallel tests. Near-universal here
(`~2,377` files). Requires tests to be independent — hence `newSuite()` per sub-test and no shared
mutable state.

### `context.WithTimeout`
The house rule: every test builds its context with `context.WithTimeout(context.Background(),
15*time.Second)` so a hung call fails the test instead of blocking forever.

### `newSuite` / `assertExpected`
The canonical structure (`go-test-style.md`): an **inline factory** `newSuite()` that builds a fresh
`testSuite{ sut, db, tx, mockRepo }` for each sub-test, and an **inline helper** `assertExpected` that
runs `mock.AssertExpectationsForObjects(t, s.db, s.tx, s.mockRepo)`. Both defined *inside* the test
function, not at package level.

### arrange / act / assert
The three comment-marked sections inside every sub-test: **arrange** (build the suite, program the
mocks), **act** (call the method under test), **assert** (check the result + verify the mocks). A
required convention here.

### SUT (system under test)
The thing being tested — the `sut` field in the suite (a handler, service, or repo). Everything else
in the suite is a collaborator, mocked.

### test double
The umbrella term (Fowler) for any stand-in used in a test: **dummy** (passed but unused), **stub**
(returns canned answers), **spy** (records calls), **fake** (a working lightweight impl), and
**mock** (pre-programmed with expectations it *verifies*). This repo's "mocks" are true mocks — they
assert they were called.

### mock (testify `mock.Mock`)
A generated type embedding `testify/mock`'s `mock.Mock`. You **program** it with `.On(method,
args…).Return(values…)` and **verify** it with `AssertExpectations`. 100% of this repo's mocking is
testify; there is no gomock.

### `.On(...).Return(...)` / `.Once()`
Program an expectation: "when `method` is called with these args, return these values." `.Once()`
asserts it's called exactly once. Unset calls with a matching signature that were programmed but never
called fail `AssertExpectations`.

### `mock.MatchedBy`
An argument matcher taking a predicate: `mock.MatchedBy(func(e *model.Email) bool { … })`. Lets an
expectation assert on the *contents* of a complex argument (e.g. the entity's fields), not just its
presence. The house way to check "the right thing was passed."

### `mock.Anything` / `mock.AnythingOfType`
Wildcard argument matchers — "any value" / "any value of this type." Used when an argument's exact
value doesn't matter to the case (e.g. the generated SQL string, a context).

### `AssertExpectationsForObjects`
`mock.AssertExpectationsForObjects(t, m1, m2, …)` — verifies that every programmed `.On` on each mock
was actually called. The house "did the code do what I said it would?" check (`assertExpected`).

### the two generators
This repo generates mocks two ways: **`GenMockStructs`** — a bespoke **reflection** codegen
(`mock_struct.go`) for concrete structs (`MockEmailRepo`), and **`GenMockInterfaces`** — a wrapper
over real **`mockery`** for named interfaces. Both emit testify mocks into `mock/`.

### `gen-mock` (the Make targets)
`make gen-mock-v2` (eureka_v2) / `make service=<svc> gen-mock-service` — run the custom
`cmd/utils/mock` CLI to regenerate a service's mocks. The rule: **after changing an interface,
regenerate**, or the mocks go stale and break the build.

### the misleading header
Reflection-generated mocks carry `// Code generated by mockgen. DO NOT EDIT.` — but it is **not**
gomock/mockgen; it's the bespoke `mock_struct.go`. A gotcha worth knowing.

### `mock/` directory
The generated-mock tree, mirroring `internal/` one-to-one. `mock/golibs/database` (Ext/Tx/Row/Rows),
per-service mocks, and `mock/testutil`. Never edit by hand — regenerate.

### `mock_database.Ext` / `.Tx`
The generated mocks of the DB interfaces (`database.Ext` = query/exec + `Begin`; `database.Tx` =
`Commit`/`Rollback` + query/exec). What a usecase test uses to fake the database and its transactions.

### `testutil.MockDB`
The house DB-testing toolkit (`mock/testutil/`). Bundles the DB mocks and gives helpers —
`MockExecArgs`, `MockQueryArgs`, `MockScanArray` — that fake pgx's `Scan` (copying values into the
caller's destinations via reflection) and can even parse the emitted SQL. How you unit-test a
repository without a database.

### `-count=3`
The flag on `unit-test-service` that runs the suite three times — a flake/ordering detector.
Consequence: tests must be deterministic and parallel-safe (no leaked state between runs).

### coverage (`-cover`)
`go test -cover` reports the percentage of statements executed by the tests. The house target is a
**soft >80% case coverage per function** (the coverage checklist), and the coverage profile strips
generated code.

### scope boundary
The line this course stops at: **unit tests only.** Excluded — anything under `features/` or
`internal/gandalf`, anything run by `godog` / `local/run.bash bdd`, and repo tests that hit a real
database. Those are BDD/E2E/integration, a separate world needing the Docker stack.