Generate Mutants for a Single R File — mutate

Creates mutants for a single R source file by combining AST-based mutations from the C++ mutation engine with fallback line-deletion mutants.

Usage

mutate_file(
  src_file,
  out_dir,
  max_mutants = NULL,
  max_line_deletions = 5,
  operators = NULL
)

Arguments

src_file: Path to an R source file.
out_dir: Directory where mutant files are written. This argument is required so that the function never writes to the current working directory unless the caller explicitly requests it.
max_mutants: Optional cap on the number of returned mutants. If set, a random subset of generated mutants is returned.
max_line_deletions: Maximum number of line-deletion mutants generated per file (a random subset of deletable lines). These complement the AST-based statement deletions by also covering top-level / non-block lines. Use 0 to disable line-deletion mutants entirely. Defaults to 5.
operators: Mutation operators to apply: a character vector of operator ids and families, read left to right, where a - prefix removes (e.g. c("default", "seq_idiom", "-bool_flip")). NULL uses the option mutator.operators, or "default" if it is unset. See mutation_operators().

Value

A list of mutants. Each element contains:

path: Path to the mutant file.
info: Formatted mutation metadata (file, source range, and details).
loc: Machine-readable location: a list with file_path, start_line, and end_line (the latter two NA when unavailable), and operator_id, the id of the mutation operator that produced the mutant (e.g. "rel_swap", "stmt_delete").

Details

Mutants that cannot change behaviour are not written: those whose code is identical to the original or to another mutant, and those that simple rules show to be equivalent (for example paste to paste0 with a single argument). A message gives their number per file.

Examples

src <- tempfile(fileext = ".R")
writeLines("add <- function(x, y) x + y", src)
mutants <- mutate_file(src, out_dir = tempfile("mutations_"), max_mutants = 1)
#> Generated 1 AST-based mutants for file1aa5404ab353.R
length(mutants)
#> [1] 1