engine

package
v0.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: Apache-2.0 Imports: 32 Imported by: 0

Documentation

Overview

Package engine orchestrates mutation testing by discovering, applying, and testing mutations.

Index

Constants

View Source
const DefaultTimeoutCoefficient = 5

DefaultTimeoutCoefficient is the default multiplier for the timeout length of each test run.

Variables

View Source
var ErrEquivalentAnnotation = errors.New("invalid equivalent mutant annotation")

ErrEquivalentAnnotation is the error of a //gremlins: directive comment that is not a valid annotation of exactly one equivalent mutant.

View Source
var TokenMutantType = map[token.Token][]mutator.Type{
	token.ADD:            {mutator.ArithmeticBase},
	token.ADD_ASSIGN:     {mutator.InvertAssignments, mutator.RemoveSelfAssignments},
	token.AND:            {mutator.InvertBitwise},
	token.AND_ASSIGN:     {mutator.RemoveSelfAssignments, mutator.InvertBitwiseAssignments},
	token.AND_NOT:        {mutator.InvertBitwise},
	token.AND_NOT_ASSIGN: {mutator.RemoveSelfAssignments, mutator.InvertBitwiseAssignments},
	token.BREAK:          {mutator.InvertLoopCtrl},
	token.CONTINUE:       {mutator.InvertLoopCtrl},
	token.DEC:            {mutator.IncrementDecrement},
	token.EQL:            {mutator.ConditionalsNegation},
	token.GEQ:            {mutator.ConditionalsBoundary, mutator.ConditionalsNegation},
	token.GTR:            {mutator.ConditionalsBoundary, mutator.ConditionalsNegation},
	token.INC:            {mutator.IncrementDecrement},
	token.LAND:           {mutator.InvertLogical},
	token.LEQ:            {mutator.ConditionalsBoundary, mutator.ConditionalsNegation},
	token.LOR:            {mutator.InvertLogical},
	token.LSS:            {mutator.ConditionalsBoundary, mutator.ConditionalsNegation},
	token.MUL:            {mutator.ArithmeticBase},
	token.MUL_ASSIGN:     {mutator.InvertAssignments, mutator.RemoveSelfAssignments},
	token.NEQ:            {mutator.ConditionalsNegation},
	token.OR:             {mutator.InvertBitwise},
	token.OR_ASSIGN:      {mutator.RemoveSelfAssignments, mutator.InvertBitwiseAssignments},
	token.QUO:            {mutator.ArithmeticBase},
	token.QUO_ASSIGN:     {mutator.InvertAssignments, mutator.RemoveSelfAssignments},
	token.REM:            {mutator.ArithmeticBase},
	token.REM_ASSIGN:     {mutator.InvertAssignments, mutator.RemoveSelfAssignments},
	token.SHL:            {mutator.InvertBitwise},
	token.SHL_ASSIGN:     {mutator.RemoveSelfAssignments, mutator.InvertBitwiseAssignments},
	token.SHR:            {mutator.InvertBitwise},
	token.SHR_ASSIGN:     {mutator.RemoveSelfAssignments, mutator.InvertBitwiseAssignments},
	token.SUB:            {mutator.InvertNegatives, mutator.ArithmeticBase},
	token.SUB_ASSIGN:     {mutator.InvertAssignments, mutator.RemoveSelfAssignments},
	token.XOR:            {mutator.InvertBitwise},
	token.XOR_ASSIGN:     {mutator.RemoveSelfAssignments, mutator.InvertBitwiseAssignments},
}

TokenMutantType is the mapping from each token.Token and all the mutator.Type that can be applied to it.

Functions

This section is empty.

Types

type CodeData

type CodeData struct {
	Cov       coverage.Profile
	Diff      diff.Diff
	Exclusion exclusion.Rules
}

CodeData is used to check if the mutant should be executed.

type Engine

type Engine struct {
	// contains filtered or unexported fields
}

Engine is the "engine" that performs the mutation testing.

It traverses the AST of the project, finds which TokenMutator can be applied and performs the actual mutation testing.

func New

func New(mod gomodule.GoModule, codeData CodeData, jDealer ExecutorDealer, opts ...Option) Engine

New instantiates an Engine.

It gets a fs.FS on which to perform the analysis, a CodeData to check if the mutants are executable and a sets of Option.

func (*Engine) Run

func (mu *Engine) Run(ctx context.Context) (report.Results, error)

Run executes the mutation testing.

It walks the fs.FS provided and checks every .go file which is not a test. For each file it will scan for tokenMutations and gather all the mutants found. A walk, open, or parse failure stops the discovery. When an executor fails, Run stops the discovery and schedules no new mutants. Run then returns the joined errors with the partial results, which the caller must not report as success. The results do not contain the failed mutants. When ctx is done, Run stops the discovery and the pending tests. Run returns only after the discovery and the workers it started have exited.

type ExecutorDealer

type ExecutorDealer interface {
	// NewExecutor returns the workerpool.Executor of mut. The executor sends
	// one ExecutorResult to outCh and calls wg.Done when it completes.
	NewExecutor(mut mutator.Mutator, outCh chan<- ExecutorResult, wg *sync.WaitGroup) workerpool.Executor
}

ExecutorDealer is the initializer for new workerpool.Executor.

type ExecutorDealerOption

type ExecutorDealerOption func(j MutantExecutorDealer) MutantExecutorDealer

ExecutorDealerOption is the defining option for the initialisation of a ExecutorDealer.

func WithExecContext

func WithExecContext(c execContext) ExecutorDealerOption

WithExecContext overrides the default exec.Command with a custom executor.

type ExecutorResult added in v0.8.0

type ExecutorResult struct {
	Mutant mutator.Mutator
	Err    error
}

ExecutorResult is the outcome of one workerpool.Executor. Each executor sends exactly one result. Err is not nil when the executor could not produce a valid status for Mutant.

type MutantExecutorDealer

type MutantExecutorDealer struct {
	// contains filtered or unexported fields
}

MutantExecutorDealer is a ExecutorDealer for the initialisation of a mutantExecutor.

By default, it sets uses exec.Command to perform the tests on the source code. This can be overridden, for example in tests.

The apply and rollback functions are wrappers around the TokenMutator apply and rollback. These can be overridden with nop functions in tests. Not an ideal setup. In the future we can think of a better way to handle this.

func NewExecutorDealer

func NewExecutorDealer(
	mod gomodule.GoModule, wdd workdir.Dealer, baseline coverage.Result, opts ...ExecutorDealerOption,
) (*MutantExecutorDealer, error)

NewExecutorDealer initialises a MutantExecutorDealer. The elapsed time and the peak memory of baseline, the coverage run, give the timeout and the memory limit of each mutant test run. It returns an error when it cannot find the memory budget.

func (MutantExecutorDealer) NewExecutor

func (m MutantExecutorDealer) NewExecutor(
	mut mutator.Mutator, outCh chan<- ExecutorResult, wg *sync.WaitGroup,
) workerpool.Executor

NewExecutor returns a new workerpool.Executor for the given mutator.Mutator. It gets an output channel of ExecutorResult and a sync.WaitGroup. The executor sends one result to the channel, and the wait group will be done when the executor is complete.

type NodeToken

type NodeToken struct {
	TokPos token.Pos
	// contains filtered or unexported fields
}

NodeToken is the reference to the actualToken that will be mutated during the mutation testing.

func NewTokenNode

func NewTokenNode(n ast.Node) (*NodeToken, bool)

NewTokenNode checks if the ast.Node implementation is supported by Gremlins and gets its Tok/Op and relative position. It returns false as second parameter if the implementation is not supported.

func (*NodeToken) SetTok

func (n *NodeToken) SetTok(t token.Token)

SetTok sets the token.Token of the tokenNode.

func (*NodeToken) Tok

func (n *NodeToken) Tok() token.Token

Tok returns the reference to the token.Token.

type Option

type Option func(m Engine) Engine

Option for the Engine initialization.

func WithDirFs

func WithDirFs(dirFS fs.FS) Option

WithDirFs overrides the fs.FS of the module (mainly used for testing purposes).

type TokenMutator

type TokenMutator struct {
	// contains filtered or unexported fields
}

TokenMutator is a mutator.Mutator of a token.Token.

Since the AST is shared among mutants, it is important to avoid that more than one mutation is applied to the same file before writing it. For this reason, TokenMutator contains a cache of locks, one for each file. Every time a mutation is about to being applied, a lock is acquired for the file it is operating on. Once the file is written and the token is rolled back, the lock is released. Keeping a lock per file instead of a lock per TokenMutator allows to apply mutations on different files in parallel.

func NewTokenMutant

func NewTokenMutant(pkg string, set *token.FileSet, file *ast.File, node *NodeToken) *TokenMutator

NewTokenMutant initialises a TokenMutator.

func (*TokenMutator) Apply

func (m *TokenMutator) Apply() error

Apply saves the original token.Token of the mutator.Mutator and sets the current token from the tokenMutations table. Apply overwrites the source code file with the mutated one. It also stores the original file in the TokenMutator in order to allow Rollback to put it back later.

The AST is shared among mutants, so Apply puts back the original token on every path before it returns. This also avoids locking in a method and unlocking in another. When the mutated file cannot be written, Apply writes back the original file and returns the error, joined with any restoration error.

func (*TokenMutator) EquivalentReason added in v0.9.0

func (m *TokenMutator) EquivalentReason() string

EquivalentReason returns the review reason of the annotation that marks the mutant as equivalent, or an empty string.

func (*TokenMutator) MutatedSnippet

func (m *TokenMutator) MutatedSnippet() []byte

MutatedSnippet returns the mutated code snippet around the mutation point.

func (*TokenMutator) OrigSnippet

func (m *TokenMutator) OrigSnippet() []byte

OrigSnippet returns the original code snippet around the mutation point.

func (*TokenMutator) Pkg

func (m *TokenMutator) Pkg() string

Pkg returns the package name to which the mutant belongs.

func (*TokenMutator) Pos

func (m *TokenMutator) Pos() token.Pos

Pos returns the token.Pos where the TokenMutator resides.

func (*TokenMutator) Position

func (m *TokenMutator) Position() token.Position

Position returns the token.Position where the TokenMutator resides.

func (*TokenMutator) Rollback

func (m *TokenMutator) Rollback() error

Rollback puts back the original file after the test and cleans up the TokenMutator to free memory.

func (*TokenMutator) SetEquivalentReason added in v0.9.0

func (m *TokenMutator) SetEquivalentReason(reason string)

SetEquivalentReason sets the review reason of the annotation that marks the mutant as equivalent.

func (*TokenMutator) SetStatus

func (m *TokenMutator) SetStatus(s mutator.Status)

SetStatus sets the mutator.Status of the mutant.Mutator.

func (*TokenMutator) SetType

func (m *TokenMutator) SetType(mt mutator.Type)

SetType sets the mutator.Type of the mutant.Mutator.

func (*TokenMutator) SetWorkdir

func (m *TokenMutator) SetWorkdir(path string)

SetWorkdir sets the base path on which to Apply and Rollback operations.

By default, TokenMutator will operate on the same source on which the analysis was performed. Changing the workdir will prevent the modifications of the original files.

func (*TokenMutator) Status

func (m *TokenMutator) Status() mutator.Status

Status returns the mutator.Status of the mutant.Mutator.

func (*TokenMutator) Type

func (m *TokenMutator) Type() mutator.Type

Type returns the mutator.Type of the mutant.Mutator.

func (*TokenMutator) Workdir

func (m *TokenMutator) Workdir() string

Workdir returns the current working dir in which the Mutator will apply its mutations.

Directories

Path Synopsis
Package workdir manages temporary working directories for isolated mutation testing.
Package workdir manages temporary working directories for isolated mutation testing.
Package workerpool provides a worker pool for concurrent mutation testing execution.
Package workerpool provides a worker pool for concurrent mutation testing execution.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL