Documentation
¶
Overview ¶
Package engine orchestrates mutation testing by discovering, applying, and testing mutations.
Index ¶
- Constants
- Variables
- type CodeData
- type Engine
- type ExecutorDealer
- type ExecutorDealerOption
- type ExecutorResult
- type MutantExecutorDealer
- type NodeToken
- type Option
- type TokenMutator
- func (m *TokenMutator) Apply() error
- func (m *TokenMutator) EquivalentReason() string
- func (m *TokenMutator) MutatedSnippet() []byte
- func (m *TokenMutator) OrigSnippet() []byte
- func (m *TokenMutator) Pkg() string
- func (m *TokenMutator) Pos() token.Pos
- func (m *TokenMutator) Position() token.Position
- func (m *TokenMutator) Rollback() error
- func (m *TokenMutator) SetEquivalentReason(reason string)
- func (m *TokenMutator) SetStatus(s mutator.Status)
- func (m *TokenMutator) SetType(mt mutator.Type)
- func (m *TokenMutator) SetWorkdir(path string)
- func (m *TokenMutator) Status() mutator.Status
- func (m *TokenMutator) Type() mutator.Type
- func (m *TokenMutator) Workdir() string
Constants ¶
const DefaultTimeoutCoefficient = 5
DefaultTimeoutCoefficient is the default multiplier for the timeout length of each test run.
Variables ¶
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.
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 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 ¶
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 ¶
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
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 ¶
NodeToken is the reference to the actualToken that will be mutated during the mutation testing.
func NewTokenNode ¶
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.
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 ¶
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.
Source Files
¶
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. |