modality mutate

Command: modality mutate

mutate is used to inject a mutation, perturbing a running system under test into a new state. This command has two chief variants:

  1. A manual mutation variant in which a specific mutation to the system is dictated by the user.
  2. An automatic mutation variant in which the modality system is asked to perturb the system under test in some automatically-determined fashion.

# Manual Mutation

Command: modality mutate <mutator-expression> [mutation-argument...]

Send a specific mutation to the system under test. A manual mutation takes a mutator expression, which is an expression that uniquely identifies a mutator.

When you inject a new mutation Modality will attempt to clear out all prior mutations unless you pass the --retain-mutation-epoch option.

# Manual Mutation Examples

$ modality mutate "my-mutator@my-probe" 1 false 4.5

$ modality mutate "my-mutator@my-probe" b=false a=1 c=4.5

# Details

The <mutator-expression> takes the form <mutator-definition-identifier>@<probe-identifier>.

A <mutator-definition-identifier> is one of:

  • A mutator’s name, if it is globally unique for the entire SUT.
  • The mutator’s component name and the mutator's name, joined by a colon:
    • <component-name>:<mutator-name>
  • The mutator’s component id and the mutator's name, joined by a colon:
    • <component-id>:<mutator-name>

Note that the unsigned integer which represents the hash of the mutator's definition can also be substituted for the mutator's name in any case.

A <probe-identifier> is one of:

  • A probe's name, if it is globally unique for the entire SUT.
  • The probe's component name and the probe's name, joined by a colon:
    • <component-name>:<probe-name>
  • The probe's component id and the probe's name, joined by a colon:
    • <component-id>:<probe-name>

Note that the probe’s numeric id can be used in the place of its name in any case.

The [mutation-argument...] values (space separated) are used to parameterize the mutation injection when it occurs. The acceptable argument values are specific to the mutator and are position-sensitive. You can list available mutators and inspect parameter information with the modality sut mutator command.

The form for writing mutation arguments is as bare values, following the positional order of the mutator's argument definitions. For a mutator named my-mutator with an integer argument a, a boolean argument b, and a float argument c, a mutation could be manually injected with positional argument values like so:

$ modality mutate "my-mutator@my-probe" 1 false 4.5

Alternately, the names of the mutator arguments could be used to supply the arguments on the command line in any desired order. For example, for the same mutator with three arguments, a mutation could be manually injected like so:

$ modality mutate "my-mutator@my-probe" b=false a=1 c=4.5

NOTE

All arguments in the mutator's definition must always be specified in the CLI.

# Automatic Mutation

Command: modality mutate

Send a modality-generated mutation into the system under test. This variant is identified by its lack of a specific mutator-expression parameter.

When you inject a new mutation Modality will attempt to clear out all prior mutations unless you pass the --retain-mutation-epoch option.

# Automatic Mutation Example

$ modality mutate --tags=battery

# Options

--allow-outside-safety-range - Allow mutation to occur with values that are outside the defined safety ranges of mutator arguments.

--objective-name <objective-name> - Objective name to be associated with this mutation. For automatic mutations, this objective may constrain what mutations get generated.

--retain-mutation-epoch - Retain the current mutation epoch with this mutation. This allows adding additional mutations to the same mutation epoch as determined from a previous mutation. If this flag is not provided, a new mutation epoch is constructed for this mutation.

--using <session name> - Use the given session rather than the default one.

--precondition <precondition> - A precondition trace expression that constrains when mutation should occur. A mutation is only applied after the precondition trace expression has a result. Mutually exclusive with --precondition-file.

--precondition-file <precondition-file> - A file containing a precondition trace expression that constrains when mutation should occur. A mutation is only applied after the precondition trace expression has a result. Mutually exclusive with --precondition.

--probes=<probes> - A semicolon delimited list of probe identifiers. Automatic mutation will only be done using mutators associated with one of the specified probes.

--tags=<tags> - A semicolon delimited list of mutator tags. Automatic mutation will only be done using mutators which have at least one of the specified tags.