Documentation
¶
Overview ¶
Package gobuildrunner runs a package's tests from a binary it builds itself, once, instead of invoking `go test` for every mutant.
This is the capability ditto did not have. It knew a command string and ran it, so every mutant paid the fixed cost of starting `go test` — measured at 750-950 ms regardless of what the suite does, and 84% of a run. Compiling once only helps when the compiled thing stops changing between mutants, which is what internal/schemata is for; the two are useless apart.
Index ¶
- Constants
- type GoBuildRunner
- type ModuleScopeRunner
- func (r *ModuleScopeRunner) Built() bool
- func (r *ModuleScopeRunner) Compilations() int
- func (r *ModuleScopeRunner) ConverterStarts() int
- func (r *ModuleScopeRunner) Discoveries() int
- func (r *ModuleScopeRunner) PackageRuns() int
- func (r *ModuleScopeRunner) ScopeTo(directory string)
- func (r *ModuleScopeRunner) Select(mutant int)
- func (r *ModuleScopeRunner) Selections() int
- func (r *ModuleScopeRunner) SetCompilationDirectory(directory string)
- func (r *ModuleScopeRunner) SkippedPackages() int
- func (r *ModuleScopeRunner) Test(repository ditto.TemporaryRepository) result.Result[string]
- func (r *ModuleScopeRunner) Toolchain() string
- func (r *ModuleScopeRunner) ToolchainStarts() int
Constants ¶
const Selected = "DITTO_MUTANT"
Selected is the environment variable a gated file reads to know which mutant it is being asked for. Zero, or absent, selects none.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type GoBuildRunner ¶
type GoBuildRunner struct {
// contains filtered or unexported fields
}
GoBuildRunner builds the tests of one package and then runs that binary.
One package, because `go test -c` compiles one package's tests. That is the shape of the case this is for: a change staged in one package, run while the code is still being written.
func New ¶
func New(packagePath string) *GoBuildRunner
func (*GoBuildRunner) Built ¶
func (r *GoBuildRunner) Built() bool
Built reports whether there is a binary to run. A package that does not compile leaves this false, and the caller falls back rather than being killed by a build it shares with every other mutant.
func (*GoBuildRunner) Compilations ¶
func (r *GoBuildRunner) Compilations() int
Compilations and Runs are exact counters, which is what the performance of this is allowed to be judged on. Wall clock varies by more than half on a working machine; these do not vary at all.
func (*GoBuildRunner) Runs ¶
func (r *GoBuildRunner) Runs() int
func (*GoBuildRunner) Select ¶
func (r *GoBuildRunner) Select(mutant int)
Select is which mutant the next run asks the binary for.
func (*GoBuildRunner) Test ¶
func (r *GoBuildRunner) Test(repository ditto.TemporaryRepository) result.Result[string]
func (*GoBuildRunner) Toolchain ¶
func (r *GoBuildRunner) Toolchain() string
Toolchain is the absolute path of the `go` binary this runner builds with, or empty when none could be found.
type ModuleScopeRunner ¶ added in v0.11.0
type ModuleScopeRunner struct {
// contains filtered or unexported fields
}
ModuleScopeRunner compiles the default module test scope once and executes every resulting package test binary for each selected mutant.
func NewModuleScope ¶ added in v0.11.0
func NewModuleScope() *ModuleScopeRunner
NewModuleScope returns a runner for the exact default ./... Go test scope.
func (*ModuleScopeRunner) Built ¶ added in v0.11.0
func (r *ModuleScopeRunner) Built() bool
Built is true only after discovery, layout validation, compilation, and every expected test-binary check has succeeded.
func (*ModuleScopeRunner) Compilations ¶ added in v0.11.0
func (r *ModuleScopeRunner) Compilations() int
Compilations counts complete-scope go test -c invocations.
func (*ModuleScopeRunner) ConverterStarts ¶ added in v0.11.0
func (r *ModuleScopeRunner) ConverterStarts() int
ConverterStarts counts conversions of a failing package's output into the stream internal/verdict reads a reason from. A green selection starts none, because a reason is only ever asked of a kill.
func (*ModuleScopeRunner) Discoveries ¶ added in v0.11.0
func (r *ModuleScopeRunner) Discoveries() int
Discoveries counts structured package-layout discovery attempts.
func (*ModuleScopeRunner) PackageRuns ¶ added in v0.11.0
func (r *ModuleScopeRunner) PackageRuns() int
PackageRuns counts started package test binaries.
func (*ModuleScopeRunner) ScopeTo ¶ added in v0.11.0
func (r *ModuleScopeRunner) ScopeTo(directory string)
ScopeTo declares the repository-relative directory of the package whose mutation this batch selects, so only the test binaries that can observe it are started.
It is optional on purpose. A runner with no scope runs every package, which is what this did before the closure was measured, so a caller that never declares one loses nothing but time.
func (*ModuleScopeRunner) Select ¶ added in v0.11.0
func (r *ModuleScopeRunner) Select(mutant int)
Select chooses the mutant test binaries receive through Selected.
func (*ModuleScopeRunner) Selections ¶ added in v0.11.0
func (r *ModuleScopeRunner) Selections() int
Selections counts baseline and mutant selections answered by Test.
func (*ModuleScopeRunner) SetCompilationDirectory ¶ added in v0.11.0
func (r *ModuleScopeRunner) SetCompilationDirectory(directory string)
SetCompilationDirectory writes this runner's test binaries into a directory chosen by the caller, so the batches of one release reuse one instead of each building its own.
It only pays together with a sandbox that is reused too. A fresh directory per batch throws away the toolchain's up-to-date check; a fresh sandbox per batch defeats it anyway, because Go's build IDs cover the package directories. Measured both ways: the shared directory alone bought nothing at all.
func (*ModuleScopeRunner) SkippedPackages ¶ added in v0.11.0
func (r *ModuleScopeRunner) SkippedPackages() int
SkippedPackages counts package test binaries not started because the mutated package is not in what they compile. It is the counter the scoping change is judged on, and it says nothing unless ScopeTo was called.
func (*ModuleScopeRunner) Test ¶ added in v0.11.0
func (r *ModuleScopeRunner) Test(repository ditto.TemporaryRepository) result.Result[string]
Test preserves the package runner's result contract: Ok means a command or test failed, while Err means every package test passed.
func (*ModuleScopeRunner) Toolchain ¶ added in v0.11.0
func (r *ModuleScopeRunner) Toolchain() string
Toolchain is the resolved Go executable, or empty when none could be found.
func (*ModuleScopeRunner) ToolchainStarts ¶ added in v0.11.0
func (r *ModuleScopeRunner) ToolchainStarts() int
ToolchainStarts counts go list and go test process starts.
Source Files