Package {mutator}

The prompt to send to the API

API configuration with key and model information

Requests refused for rate limiting (HTTP 429) or by an overloaded gateway (502, 503, 504) are retried with exponential backoff, honouring a Retry-After header when the server sends one. Network errors are retried twice. A request may wait up to 30 minutes for the first byte of the answer, as reasoning models send nothing while they think.

Maximum number of requests, including the first one.

String containing the original source code

List of mutant details including IDs and mutation info

Directory to search for a .openai_config file. Only this directory is consulted (parent directories are not). Defaults to the current working directory; pass NULL to ignore config files.

Path to the original source file

List of mutants that survived test execution

Optional API configuration (will be loaded if NULL)

Maximum number of mutants sent in a single API request. Smaller batches keep each response short enough to avoid truncation (which silently drops verdicts) and let batches run concurrently. Defaults to 25.

Number of API requests to run concurrently (requires a forking platform). Defaults to 1 (sequential).

Whether to print per-file progress and an equivalence summary to the console. Defaults to TRUE. mutate_package() sets this to FALSE when running many files in parallel, so it can print one aggregated summary (and a single progress bar) instead of one per batch.

Path to an R source file.

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.

Optional cap on the number of returned mutants. If set, a random subset of generated mutants is returned.

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.

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

Path to the package directory.

Number of parallel workers used for mutant test execution.

Logical; if TRUE, prints per-mutant logs, timeout info, and the mutation score per operator.

Logical; if TRUE, every generated mutant is analyzed for equivalence using the OpenAI-based workflow before the test suites are run. Mutants judged equivalent are recorded as survived without running their tests, as no test can kill an equivalent mutant; the remaining mutants are tested as usual.

Optional directory to store generated mutant files. If NULL, a temporary directory is used.

Sample that number of mutants for testing. If NULL, all mutants are tested.

Optional timeout in seconds for each mutant run. If NULL, timeout is derived from baseline runtime with a small minimum floor. Still works with compiled native code.

Directory searched for a .openai_config file when detectEqMutants = TRUE (see get_openai_config()). Defaults to the current working directory.

Maximum number of line-deletion mutants per .R file (passed to mutate_file()); 0 disables them. Defaults to 0, since line-deletion mutants are largely redundant with the AST block-deletion mutants generated by default.

Logical; if TRUE (the default), tests run in "CRAN mode": the NOT_CRAN environment variable is set to "false" in the test subprocess so testthat::skip_on_cran() / skip_if_offline() guards take effect and the same tests CRAN would run are used (skipping network/slow tests the package marks). Set to FALSE to run the full suite (NOT_CRAN = "true"), as devtools::test() does.

Logical; if TRUE (the default), a mutant's test run stops at the first failing test rather than running the whole suite. A mutant is KILLED as soon as one test detects it, so the remainder of the suite is wasted work. Set to FALSE to run the full suite for every mutant. Applies to the testthat strategy; the tinytest strategy always runs the full set of selected test files, and the installed-tests fallback already stops at the first failing test file regardless of this flag.

Logical; if FALSE (the default), each mutant's package copy symlinks the unchanged directories of the original package (only the mutated ⁠R/⁠ file is materialised), which is fast but makes those directories shared writable state across the parallel workers. If TRUE, the ⁠src/⁠ and ⁠tests/⁠ directories (or ⁠src/⁠ and ⁠inst/⁠ under the tinytest strategy) are deep-copied into every mutant copy instead. Use isolate = TRUE when a package has non-hermetic tests that write files into ⁠tests/⁠ (or ⁠src/⁠) and parallel runs therefore produce spurious KILLED/HANG verdicts; it gives each worker its own copy at the cost of extra disk. Note that running with cores = 1 avoids such contention without the copy cost.

Optional character vector of shell-style glob patterns (e.g. "import-standalone-*") matched against the base names of the .R files in ⁠R/⁠. Matching files are skipped entirely before any mutants are generated. NULL (the default) mutates every file. This complements the in-source ⁠# mutator:ignore-file⁠ and ⁠# mutator:ignore-start⁠ / ⁠# mutator:ignore-end⁠ directives, which exclude a whole file or a line region from within the source itself, optionally only for the operators they list (e.g. ⁠# mutator:ignore-start seq_idiom, constants⁠). Note that for operator mutations the engine only resolves positions to the enclosing top-level definition, so a region directive excludes that function's operator mutants as a group (line-deletion mutants are excluded line-precisely).

Test strategy to use. "auto" (the default) picks the testthat strategy when ⁠tests/testthat/⁠ exists, the tinytest strategy when ⁠inst/tinytest/⁠ exists, and the installed-tests strategy otherwise. "testthat" forces the in-process testthat::test_dir() path (requires ⁠tests/testthat/⁠). "tinytest" forces the in-process tinytest::run_test_dir() path (requires ⁠inst/tinytest/⁠). Both in-process strategies load the package with pkgload::load_all(), which does not dispatch S4 methods defined on ...-dispatching base generics such as seq(); a package that relies on those will fail the baseline, and the error points to "tinytest-installed". "tinytest-installed" runs the tinytest suite against an installed copy (⁠R CMD INSTALL⁠ + tinytest::test_package(), requires ⁠inst/tinytest/⁠): slower than dev-mode but matches an installed package (correct S4 dispatch) and still supports coverage guidance. "installed" forces the ⁠R CMD INSTALL --install-tests⁠ + tools::testInstalledPackage() path (requires ⁠tests/⁠).

Logical; if TRUE, only the tests that actually exercise a mutant's mutated line(s) are run for that mutant, instead of the whole suite. Coverage is measured once on the unmutated package with covr. A mutant on a line no test covers cannot be killed, so it is reported SURVIVED without running any test. Selection is at the test-file level; under the assumption that the suite deterministically exercises the code, it should not change a mutant's verdict, only which tests run. Defaults to TRUE. Coverage guidance is available under the testthat, tinytest, and tinytest-installed strategies; when the resolved strategy is the generic installed-tests fallback, mutator emits a warning and runs the full suite for every mutant. Pass FALSE to disable it (and silence that warning).

How coverage_guided attributes coverage to tests under the testthat strategy (ignored when coverage_guided = FALSE and for the tinytest strategies, which have a single per-file driver). "record_tests" (the default) uses covr's record_tests in a single run; it relies only on covr's public output but, because covr credits a covered line to the deepest test-directory frame, code reached through a ⁠helper-*.R⁠/⁠setup-*.R⁠ wrapper is attributed to the helper rather than the originating ⁠test-*.R⁠ file, and such mutants conservatively run the whole suite. "per_file" instruments the package once and runs the suite a single time through a reporter that snapshots coverage per test file, giving exact file-level attribution (no helper fallback) at roughly the same cost; it depends on covr internals, so it is opt-in.

Optional desired half-width of the confidence interval on the mutation score, as a proportion (e.g. 0.05 for +/-5 percentage points). When set, the number of mutants to sample is derived from it using worst-case (p = 0.5) sizing at confidence, finite-population corrected and capped at the number of mutants generated (if the requested precision needs more mutants than exist, all are tested). Mutually exclusive with max_mutants. The required sample size depends on the target precision, not on program size (Gopinath et al., ISSRE 2015).

Confidence level for target_margin sizing and for the Wilson confidence interval reported on a sampled mutation score. Default 0.95.

Maximum number of surviving mutants to print to the console; the remainder are summarised as "... and N more" but always remain in the returned package_mutants. Use Inf to print every survivor. Default 50.

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

API key string.

Model name (e.g. "gpt-4").

Base URL of an OpenAI-compatible Chat Completions API, such as "https://api.openai.com/v1" or another provider endpoint.

Maximum number of equivalence-detection API requests to run concurrently. Use this to stay under a provider's per-key parallel-request limit (exceeding it returns HTTP 429). NA (the default) imposes no cap beyond the run's own cores.