Documentation
¶
Overview ¶
Package harness provides a reusable shared compile-corpus test helper for the db-catalyst compatibility test program.
Fixture directory contract ¶
Each fixture directory passed to the harness functions must contain:
- db-catalyst.toml — pipeline configuration (package, out, schemas, queries, …)
- schema.sql and query SQL files referenced by the config
- go.mod with "module fixture" and any external imports required by the generated package (e.g. modernc.org/sqlite for behavioral fixtures)
The harness copies the fixture directory into a fresh testing.T.TempDir, runs the pipeline there, and then compiles (and optionally runs) the result. Because the go.mod lives in the fixture, all import paths are resolved relative to that module — no separate go.sum bootstrapping is required for pure-stdlib fixtures; external-dependency fixtures must include a go.sum or the harness will run "go mod tidy" automatically.
Adding a fixture ¶
Drop a new subdirectory containing the above files under the corpus directory. No code changes are needed: CompileCorpus and DiscoverFixtures pick it up automatically.
Index ¶
- func CompileCorpus(t *testing.T, corpusDir string)
- func CompileFixture(t *testing.T, fixtureDir string) pipeline.Summary
- func CompileTempDir(t *testing.T, tmpDir string)
- func DiscoverFixtures(corpusDir string) ([]string, error)
- func GenerateFixture(t *testing.T, fixtureDir string) pipeline.Summary
- func GenerateFixtureAllowDiag(t *testing.T, fixtureDir string) (pipeline.Summary, error)
- func HasColumn(sum pipeline.Summary, table, col string) bool
- func HasTable(sum pipeline.Summary, table string) bool
- func RunBehavioralFixture(t *testing.T, fixtureDir string)
- func RunPipelineFromDir(t *testing.T, preparedDir string) (pipeline.Summary, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CompileCorpus ¶
CompileCorpus discovers every fixture in corpusDir via DiscoverFixtures and runs a t.Run sub-test for each, calling CompileFixture. Adding a fixture directory is the only step required to add a new test.
This function is intentionally slow and is skipped when -short is set.
func CompileFixture ¶
CompileFixture is the common case: it generates the fixture followed by CompileTempDir, and returns the pipeline summary so callers can additionally inspect the catalog/diagnostics (or ignore it). It fails the test if either generation or compilation fails.
This function is intentionally slow (it shells out to the Go toolchain) and is skipped when -short is set.
func CompileTempDir ¶
CompileTempDir compiles all Go packages under tmpDir using "go build ./...". If the fixture's go.mod references external modules (detected by the presence of a "require" directive that references packages outside the standard library), "go mod tidy" is run first to fetch any missing dependencies.
The test is failed with the combined build output if compilation fails. This function is intentionally slow (it shells out to the Go toolchain) and is skipped when -short is set.
func DiscoverFixtures ¶
DiscoverFixtures returns the sub-directories of corpusDir that contain a "db-catalyst.toml" file, in lexicographic order. Each returned path is relative to the caller's working directory (i.e. as passed — not resolved to an absolute path), preserving the convention used in table-driven tests.
func GenerateFixture ¶
GenerateFixture copies fixtureDir's contents into a fresh t.TempDir(), runs the pipeline on the copied db-catalyst.toml, and returns the pipeline summary. The test is failed (t.Fatal) if the pipeline returns an error; pipeline diagnostics are logged via t.Logf.
Callers that need access to the generated temp directory should use CompileFixture / RunBehavioralFixture (which compile or run the output) or the behavioral helpers below. The summary's Catalog and Diagnostics can be inspected directly via HasTable / HasColumn.
func GenerateFixtureAllowDiag ¶
GenerateFixtureAllowDiag behaves like GenerateFixture but returns the pipeline error (e.g. pipeline.DiagnosticsError) instead of failing the test. Callers use it to assert on diagnostics or error outcomes that are expected for a fixture (for example, a migration format override that intentionally produces an error). The temp directory is still created and populated; copy failures are still fatal because they indicate a broken test setup rather than a fixture outcome.
func HasColumn ¶
HasColumn reports whether the named table in the pipeline summary's catalog has a column named col. Both the table and column names are matched case-insensitively. It returns false if the summary has no catalog or the table is absent.
func HasTable ¶
HasTable reports whether the pipeline summary's catalog contains a table named table, matched case-insensitively. It returns false if the summary has no catalog.
func RunBehavioralFixture ¶
RunBehavioralFixture generates the fixture, then — if the fixture directory contains a "driver.go" file (a package main that imports the generated package and asserts behavioral correctness via os.Exit(1) on failure) — assembles a runnable module from the generated files plus driver.go, runs "go mod tidy", and executes "go run ." in the assembled temp directory. The test fails if the driver exits with a non-zero status.
If no driver.go is present, RunBehavioralFixture falls back to CompileFixture.
This function is intentionally slow and is skipped when -short is set.
func RunPipelineFromDir ¶
RunPipelineFromDir runs the db-catalyst pipeline on preparedDir, which must already contain a db-catalyst.toml (e.g. produced by sqlc2dbcat). Unlike GenerateFixture it never fails the test on a pipeline error — it returns the summary and any error so callers can inspect diagnostics themselves. This is the building block used by the realworld corpus runner.
Types ¶
This section is empty.
Source Files