engine

Documentation

Index

• Constants
• Variables
• type CodeData
• type Engine
  • func New(mod gomodule.GoModule, codeData CodeData, jDealer ExecutorDealer, ...) Engine
  • func (mu *Engine) Run(ctx context.Context) report.Results
• type ExecutorDealer
• type ExecutorDealerOption
  • func WithExecContext(c execContext) ExecutorDealerOption
• type MutantExecutorDealer
  • func NewExecutorDealer(mod gomodule.GoModule, wdd workdir.Dealer, elapsed time.Duration, ...) *MutantExecutorDealer
  • func (m MutantExecutorDealer) NewExecutor(mut mutator.Mutator, outCh chan<- mutator.Mutator, wg *sync.WaitGroup) workerpool.Executor
• type NodeToken
  • func NewTokenNode(n ast.Node) (*NodeToken, bool)
  • func (n *NodeToken) SetTok(t token.Token)
  • func (n *NodeToken) Tok() token.Token
• type Option
  • func WithDirFs(dirFS fs.FS) Option
• type TokenMutator
  • func NewTokenMutant(pkg string, set *token.FileSet, file *ast.File, node *NodeToken) *TokenMutator
  • func (m *TokenMutator) Apply() error
  • 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) 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 = 3

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

Variables

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.

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

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.

type ExecutorDealer

type ExecutorDealer interface {
	NewExecutor(mut mutator.Mutator, outCh chan<- mutator.Mutator, 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 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, elapsed time.Duration, opts ...ExecutorDealerOption) *MutantExecutorDealer

NewExecutorDealer initialises a MutantExecutorDealer.

func (MutantExecutorDealer) NewExecutor

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

NewExecutor returns a new workerpool.Executor for the given mutator.Mutator. It gets an output channel of mutator.Mutator and a sync.WaitGroup. The channel will stream the results of the executor, 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.

Apply also puts back the original Token after the mutated file write. This is done in order to facilitate the atomicity of the operation, avoiding locking in a method and unlocking in another.

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) 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.