Mutator Reference and Choosing the Right Mutators

In muttest: Mutation Testing

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
source("engine.R")

A mutator defines one kind of code change. When you pass a mutator to muttest_plan(), muttest finds every matching pattern in your source file and produces one mutant per match.

Operator mutators

operator() — custom pair

The most flexible mutator. Replaces any token with any other token.

operator("+", "-")   # every + becomes -
operator("==", "!=") # every == becomes !=

Use this when you need a specific swap not covered by the preset functions.

arithmetic_operators() — preset for arithmetic

Returns a ready-made list of operator mutators covering common arithmetic mistakes:

| Original | Mutant | | -------- | ------ | | + | - | | - | + | | * | / | | / | * | | ^ | * | | %% | * | | %/% | / |

💡 When to use: Any function that performs calculations — finance, statistics, data transformations. Arithmetic operator swaps can happen easily and go unnoticed.

plan <- muttest_plan(
  source_files = "R/finance.R",
  mutators = arithmetic_operators()
)

mad

comparison_operators() — preset for comparisons

Covers boundary and direction mistakes in comparison expressions:

| Original | Mutant | | -------- | ------ | | < | > | | > | < | | <= | >= | | >= | <= | | == | != | | != | == | | < | <= | | > | >= |

💡 When to use: Functions with threshold logic, range checks, or filter conditions. Off-by-one and direction errors are easy to introduce and hard to catch with weak tests.

shipping

logical_operators() — preset for logical operators

| Original | Mutant | | -------- | ------ | | && | \|\| | | \|\| | && | | & | \| | | \| | & |

💡 When to use: Functions with compound conditions (if (a && b)). Swapping && for || is a classic logic bug that coverage cannot detect.

access

---

Boolean literal mutators

boolean_literal() — flip TRUE/FALSE

boolean_literal("TRUE", "FALSE")  # TRUE → FALSE
boolean_literal("FALSE", "TRUE")  # FALSE → TRUE

💡 When to use: Functions with hard-coded boolean flags or default arguments like na.rm = TRUE, stringsAsFactors = FALSE. Flipping the default reveals whether tests exercise both states.

boolean_literals() — preset for boolean literals

Returns a ready-made list covering all canonical flips:

| Original | Mutant | | -------- | ------- | | TRUE | FALSE | | FALSE | TRUE | | T | F | | F | T |

plan <- muttest_plan(
  source_files = "R/flags.R",
  mutators = boolean_literals()
)

---

Numeric mutators

numeric_increment() — add 1 to every numeric literal

numeric_increment()  # 5 → 6, 0 → 1, 100 → 101

numeric_decrement() — subtract 1 from every numeric literal

numeric_decrement()  # 5 → 4, 1 → 0, 100 → 99

💡 When to use: Functions where exact numeric constants matter — thresholds, window sizes, counts, index boundaries. Off-by-one errors in constants are common and often untested.

numeric_literals() — preset for numeric constants

Returns numeric_increment() and numeric_decrement() together.

plan <- muttest_plan(
  source_files = "R/thresholds.R",
  mutators = numeric_literals()
)

---

String mutators

string_empty() — replace strings with ""

string_empty()  # "hello" → ""

string_fill() — replace empty strings with "mutant"

string_fill()  # "" → "mutant"

💡 When to use: string_empty() is useful for functions that return or compare string values — it checks whether your tests would notice a blank output. string_fill() tests whether your code handles non-empty strings where empty ones are expected.

string_literals() — preset for string literals

Returns string_empty() and string_fill() together.

plan <- muttest_plan(
  source_files = "R/labels.R",
  mutators = string_literals()
)

---

Condition mutators

negate_condition() — wrap condition in !(...)

negate_condition()
# if (x > 0)   →   if (!(x > 0))
# while (done) →   while (!(done))

remove_condition_negation() — strip leading !

remove_condition_negation()
# if (!done)  →  if (done)
# if (!valid) →  if (valid)

remove_negation() — remove ! anywhere

remove_negation()
# !is.na(x)    →  is.na(x)
# !is.null(y)  →  is.null(y)

💡 When to use: Functions with guard clauses and early returns. These mutators reveal whether your tests cover both branches of a condition. A surviving negate_condition() mutant means the test inputs never trigger the FALSE branch.

condition_mutations() — preset for condition logic

Returns negate_condition() and remove_condition_negation() together.

plan <- muttest_plan(
  source_files = "R/validation.R",
  mutators = condition_mutations()
)

---

Function call mutator

call_name() — swap one function name for another

call_name("any", "all")   # any(x) → all(x)
call_name("min", "max")   # min(x) → max(x)
call_name("sum", "prod")  # sum(x) → prod(x)

💡 When to use: Functions that delegate to summary or aggregation helpers. any vs all and min vs max are among the easiest mistakes to make and the hardest to spot in a review.

---

---

NA and NULL mutators

na_literal() — swap NA/NULL values

na_literal("NA", "NULL")          # NA → NULL
na_literal("NULL", "NA")          # NULL → NA
na_literal("NA", "NA_real_")      # NA → NA_real_
na_literal("NA_real_", "NA")      # NA_real_ → NA

💡 When to use: Functions that accept or return NA or NULL, especially any code with is.na(), is.null(), or na.rm handling. Swapping NA for NULL (and vice versa) reveals whether callers distinguish between "value is missing" and "value is absent" — two distinct concepts that R treats very differently.

Swapping between typed NAs (NA_real_, NA_integer_, NA_character_) and plain NA checks whether type-sensitive downstream code (e.g. vapply, dplyr::mutate) is covered.

na_literals() — preset for NA and NULL

Returns mutators for all common NA/NULL swaps:

| Original | Mutant | | --------------- | --------------- | | NA | NULL | | NULL | NA | | NA | NA_real_ | | NA_real_ | NA | | NA | NA_integer_ | | NA_integer_ | NA | | NA | NA_character_ | | NA_character_ | NA |

plan <- muttest_plan(
  source_files = "R/missing.R",
  mutators = na_literals()
)

---

Return value mutators

replace_return_value() — replace explicit return values

replace_return_value()       # return(x) → return(NULL)
replace_return_value("NA")   # return(x) → return(NA)

💡 When to use: Any function with explicit return() calls. Tests that only check that a function runs without error or returns something will not kill these mutants — only tests that assert the specific value returned will.

A surviving replace_return_value() mutant means the caller never checks what came back from that branch. This is especially common in functions with multiple early-exit return() paths where only the happy path is tested.

Only explicit return(expr) calls are targeted; implicit returns (the last expression of a function body) are not affected.

---

Index and subscript mutators

index_increment() — shift subscript indices up by one

index_increment()   # x[i] → x[i + 1L],  x[[i]] → x[[i + 1L]]

index_decrement() — shift subscript indices down by one

index_decrement()   # x[i] → x[i - 1L],  x[[i]] → x[[i - 1L]]

💡 When to use: Functions that index into vectors or lists by position or by a computed variable. Off-by-one errors in indexing are among the most common silent bugs in R — they produce a different element rather than an error, so they pass all tests unless a specific element value is asserted.

Only simple indices are mutated: plain identifiers (x[i]) and numeric literals (x[1], x[1L]). Complex expressions like x[a + b] or x[seq_len(n)] are left untouched, keeping the mutant count focused and the signal-to-noise ratio high.

Both single-bracket ([) and double-bracket ([[) indexing are covered.

index_mutations() — preset for subscript indices

Returns index_increment() and index_decrement() together.

plan <- muttest_plan(
  source_files = "R/selectors.R",
  mutators = index_mutations()
)

---

Recommended starting set

If you are unsure where to begin, start here:

p <- muttest_plan(
  source_files = "R/my_file.R",
  mutators = c(
    arithmetic_operators(),
    comparison_operators(),
    logical_operators(),
    condition_mutations(),
    numeric_literals(),
    list(remove_negation())
  )
)

Look at the survivors, then layer in boolean_literals(), na_literals(), string_literals(), or index_mutations() for the specific patterns in your code.

The better you know your codebase, the more you can target mutators to the patterns that are most likely to harbor bugs. For example, if your code has a lot of if statements but no numeric constants, condition mutators will be more effective than numeric ones.

You'll figure it out as you go.

muttest documentation built on May 14, 2026, 5:10 p.m.