WASM-TOOLS(1)

NAME
wasm-tools mutate - A WebAssembly test case mutator.

SYNOPSIS
wasm-tools mutate [OPTIONS] [INPUT]

DESCRIPTION
A WebAssembly test case mutator.

`wasm-mutate` takes in an existing Wasm module and then applies a pseudo-random transformation to it, producing a new, mutated Wasm module. This new, mutated Wasm module can be fed as a test input to your Wasm parser, validator, compiler, or any other Wasm-consuming tool. `wasm-mutate` can serve as a custom mutator for mutation-based fuzzing.

## Example

Perform a random mutation on an existing Wasm module:

$ wasm-mutate ./input.wasm --seed 1234 -o output.wasm

## Exit Codes

* 0: Success

* 1: An unexpected failure occurred.

* 2: Failed to parse or validate the input Wasm module.

* 3: Failed to mutate the Wasm module with the given seed and mutation constraints. (Happens rarely with reasonable constraints; try again with a new seed or loosen your constraints.)

* 4: Ran out of fuel before successfully applying a mutation.

* 5: The input Wasm module uses a Wasm feature or proposal that is not yet supported by `wasm-mutate`.

* 6: Other error.

  Arguments:

    [INPUT]

    Input file to process.

    If not provided or if this is `-` then stdin is read entirely and processed. Note that for most subcommands this input can either be a binary `*.wasm` file or a textual format `*.wat` file.

OPTIONS

--generate-dwarf <lines|full>

    Optionally generate DWARF debugging information from WebAssembly text files.

    When the input to this command is a WebAssembly text file, such as `*.wat`, then this option will instruct the text parser to insert DWARF debugging information to map binary locations back to the original source locations in the input `*.wat` file. This option has no effect if the `INPUT` argument is already a WebAssembly binary or if the text format uses `(module binary ...)`.

-g

    Shorthand for `--generate-dwarf full`

-o, --output <OUTPUT>

    Where to place output.

    If not provided then stdout is used.

-v, --verbose...

    Use verbose output (-v info, -vv debug, -vvv trace)

--color <COLOR>

    Configuration over whether terminal colors are used in output.

    Supports one of `auto|never|always|always-ansi`. The default is to detect what to do based on the terminal environment, for example by using `isatty`.

    [default: auto]

-t, --wat

    Output the text format of WebAssembly instead of the binary format

-s, --seed <SEED>

    The RNG seed used to choose which transformation to apply. Given the same input Wasm and same seed, `wasm-mutate` will always generate the same output Wasm

    [default: 42]

--preserve-semantics

    Only perform semantics-preserving transformations on the Wasm module

-f, --fuel <FUEL>

    Fuel to control the time of the mutation

    [default: 18446744073709551615]

--reduce

    Only perform size-reducing transformations on the Wasm module. This allows `wasm-mutate` to be used as a test case reducer

-h, --help

    Print help (see a summary with '-h')