deviant mutation

Command: deviant mutation

Propose and manage mutations.

A mutation is an intentional change to the system under test. This could be anything from the replacement of a received message with a corrupted version to a physical force applied to an autonomous system in simulation, or even a physical change within a real system on a test bench.

This command's functionality is exposed via subcommands:

# deviant mutation clear

Command: deviant mutation clear

Clear one or all current mutations. Clearing a mutation means telling the mutator in charge of making said mutation to stop that mutation from having further effect.

# Example

$ deviant mutation clear --mutation-id 05d81bce-1236-4169-b1db-bcf9f405e503

Cleared mutation '05d81bce-1236-4169-b1db-bcf9f405e503'

Alternately,

$ deviant mutation clear

Cleared all mutations

# Options

-f, --format <text | json> - The printed output format, defaults to text.

--mutation-id <mutation id> - Optionally, the id of a particular mutation to clear. If not present, all mutations active or possibly active in the system will be cleared.

# deviant mutation create

Command: deviant mutation create

Create a mutation using one of the available mutators. You can specify the mutator responsible for the mutation precisely by using the --mutator-id option, or more generally by using the --mutator-filter to select a mutator based on its attributes.

If you select a mutator that requires parameters for its mutations, those parameters may be specified using the --params option.

# Example

$ deviant mutation create --mutator-id '7b8b756b-1378-4a20-b913-0fe259c45f6c' --params 'set_to_value=42' --params 'degrees="celsius"'

Mutation afa12bc7-ed4f-4fa5-b7f8-9bc92329f4bc
  Mutator: TempSensorFixer [7b8b756b-1378-4a20-b913-0fe259c45f6c]
  Params: _.set_to_value=42 AND _.degrees='celsius'
  Experiment: None
  Mutator Attributes:
      ...

Alternately,

$ deviant mutation create --mutator-filter '_.name = "TempSensorFixer" AND _.drone.chassis.version = 3' \
    --params 'set_to_value=42' --params 'degrees="celsius"'
    --experiment alhazen

Mutation 1300ead7-a7bc-474f-98aa-def778eb6d5a
  Mutator: TempSensorFixer [7b8b756b-1378-4a20-b913-0fe259c45f6c]
  Params: _.set_to_value=42 AND _.degrees='celsius'
  Experiment: alhazen
  Mutator Attributes:
      ...

As yet another example, one could create a mutation that was previously proposed by deviant and stored in a file.

$ deviant mutation propose --to-file sample-mutation.toml
  Mutator: TempSensorFixer [7b8b756b-1378-4a20-b913-0fe259c45f6c]
  Params: _.set_to_value=999 AND _.degrees='kelvin'
  Linked Experiment: None

$ deviant mutation create --from-file sample-mutation.toml

Mutation 8178be45-8bfe-4c2c-a74b-8995575c8a3a
  Mutator: TempSensorFixer [7b8b756b-1378-4a20-b913-0fe259c45f6c]
  Params: _.set_to_value=99 AND _.degrees='kelvin'
  Experiment: None
  Mutator Attributes:
    ...

# Options

-f, --format <text | json> - The printed output format, defaults to text.

--mutator-id <mutator id> - Optionally, the id of a particular mutator to use to create this mutation. Mutually exclusive with --mutator-filter and --from-file

--mutator-filter <mutator predicate> - An optional logical expression that specifies which mutator should be selected. Mutually exclusive with --mutator-id and --from-file

--params < key = value pair > - Each instance of this option sets the value of a parameter for this mutation. Zero to many of these may be specified, e.g. --params 'a=3' --params 'b=false', but the parameters specified should match the parameters of the related mutator.

--experiment <experiment name - An optional experiment name to associate with this mutation.

--from-file <path/to/mutation/file> - If specified, determine the mutator, the parameters, and any associated experiment for this mutation based on the contents of the file. Expects a TOML-based format, such as that produced by the deviant propose command with its --to-file option used.

# deviant mutation inspect

Command: deviant mutation inspect

Print out the information about a particular mutation.

# Example

$ deviant mutation inspect 8178be45-8bfe-4c2c-a74b-8995575c8a3a

Mutation 8178be45-8bfe-4c2c-a74b-8995575c8a3a
  Mutator: TempSensorFixer [7b8b756b-1378-4a20-b913-0fe259c45f6c]
  Params: _.set_to_value=99 AND _.degrees='kelvin'
  Experiment: None
  Mutator Attributes:
    ...

# Options

<mutation id> - Required argument. The id of the mutation to target.

-f, --format <text | json> - The printed output format, defaults to text.

# deviant mutation list

Command: deviant mutation list

Print out a list of all known mutations and some of their basic details.

# Example

$ deviant mutation list

Mutations: 2

Mutation 1300ead7-a7bc-474f-98aa-def778eb6d5a
  Mutator: TempSensorFixer [7b8b756b-1378-4a20-b913-0fe259c45f6c]
  Params: _.set_to_value=42 AND _.degrees='celsius'
  Experiment: alhazen
  Mutator Attributes:
      ...

Mutation 8178be45-8bfe-4c2c-a74b-8995575c8a3a
  Mutator: TempSensorFixer [7b8b756b-1378-4a20-b913-0fe259c45f6c]
  Params: _.set_to_value=99 AND _.degrees='kelvin'
  Experiment: None
  Mutator Attributes:
    ...

# Options

-f, --format <text | json> - The printed output format, defaults to text.

# deviant mutation propose

Command: deviant mutation propose

Suggests a possible mutation the user could create. The suggestions are limited to available mutators, and may optionally be further limited with flags like --mutator-filter or --experiment

The suggestion may be expressed as a command-line invocation to run later or as a file to edit or use at some future point.

# Example

$ deviant mutation propose

  Mutator: TempSensorFixer [7b8b756b-1378-4a20-b913-0fe259c45f6c]
  Params: _.set_to_value=999 AND _.degrees='kelvin'
  Linked Experiment: None

$ deviant mutation propose --experiment rhazes --with-invocation

  Mutator: TempSensorFixer [7b8b756b-1378-4a20-b913-0fe259c45f6c]
  Params: _.set_to_value=53 AND _.degrees='celsius'
  Linked Experiment: rhazes

Command:
deviant mutation create --mutator-id='7b8b756b-1378-4a20-b913-0fe259c45f6c' \
  --params 'set_to_value=53' \
  --params 'degrees="celsius"' \

Multiple invocations of deviant mutation propose may suggest mutations for the same mutator with different parameters or other mutators. Duplicate suggestions are possible, especially if there are few mutators or the mutators have limited parameters.

# Options

-f, --format <text | json> - The printed output format, defaults to text.

--experiment <experiment name> - If specified, the proposed mutation should match the requirements and limitations for mutations relevant to the given experiment.

--mutator-filter <mutator predicate> - An optional logical expression that specifies which mutators may be selected. Mutually exclusive with --mutator-id.

--mutator-id <mutator id> - Optionally, the id of a particular mutator to use for proposing a mutation. Mutually exclusive with --mutator-filter, as it is equivalent to filtering to exactly one precise mutator.

--to-file <path/to/mutation/file.toml> - Optionally store the mutation proposal as a TOML file. Deviant can create a mutation from this TOML file with the deviant mutation create --from-file path/to/mutation/file.toml command.

--with-invocation - Optionally print out the text of a command line invocation of Deviant which would create the proposed mutation. Does not execute this creation command text.

--workspace-name - Name of the workspace of interest. If not made explicit here, the CLI will attempt to extract it from the configuration context.

← mutator →