WASM-TOOLS(1)

👑 wasm-tools mutate, section 1 👑

okay bestie, welcome to the wasm-tools manual, and this particular page is all about the mutate subcommand, aka the WebAssembly test case mutator. and yes it's literally as iconic as it sounds. sit down, hydrate, let's go 💖

---

🦋 NAME 🦋

wasm-tools mutate — a WebAssembly test case mutator. that's it, that's the whole vibe. slay ✨

---

🎀 SYNOPSIS 🎀

wasm-tools mutate [OPTIONS] [INPUT]

short, sweet, and it will absolutely rewrite your Wasm module behind your back (consensually, with a seed 🫶).

---

🌸 DESCRIPTION 🌸

okay so. it's a WebAssembly test case mutator. but like, what does that mean?

wasm-mutate takes in an existing Wasm module and then applies a pseudo-random transformation to it, producing a new, mutated Wasm module. the way it just takes your module and goes "hmm what if not this"—and hands you something new. this new, mutated Wasm module can be fed as a test input to your Wasm parser, validator, compiler, or any other Wasm-consuming tool. so basically you're throwing curveballs at your own code and watching whether it catches them. wasm-mutate can serve as a custom mutator for mutation-based fuzzing, which is highkey its whole main character moment.

✨ Example ✨

perform a random mutation on an existing Wasm module:

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

look at that. one line. a whole new module. it's giving chaos but on purpose 💅

💀 Exit Codes 💀

bestie, the numbers matter, so memorize them, fr fr:

• 0: Success. we ate. 👑
• 1: An unexpected failure occurred. not our fault, everything is on fire. 😭
• 2: Failed to parse or validate the input Wasm module. the module walked in and immediately tripped.
• 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.) so like, rng said no. try a new seed.
• 4: Ran out of fuel before successfully applying a mutation. ⛽ empty, brain empty.
• 5: The input Wasm module uses a Wasm feature or proposal that is not yet supported by wasm-mutate. it's not you, it's ✨the spec evolution✨.
• 6: Other error. the catch-all. the "and everything else" of error codes.

🌈 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. so yes, you can pipe it. yes, you can pass a .wat. versatile queen. 🦋

---

✨ OPTIONS ✨

one bullet per option, no skips, no shortcuts (except the literal shortcuts, which are documented, obviously 💅):

• --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 ...). so like, it only does its thing in the exact right circumstances. picky but correct.

• -g — shorthand for --generate-dwarf full. tiny flag, same energy. 🎀
• -o, --output <OUTPUT> — where to place output.

if not provided then stdout is used. so careful where you're pointing that terminal, okay? 🙈

• -v, --verbose... — use verbose output (-v info, -vv debug, -vvv trace). stack 'em like bracelets. the more you add, the more it tells you. 📈
• --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. for the girlies who want to read the chaos. 🌸
• -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. deterministic behavior?? we love to see it. reproducible queen. 👑

[default: 42]

• --preserve-semantics — only perform semantics-preserving transformations on the Wasm module. lowkey respectful of your intentions. 🫶
• -f, --fuel <FUEL> — fuel to control the time of the mutation. it runs until the tank says stop.

[default: 18446744073709551615]

• --reduce — only perform size-reducing transformations on the Wasm module. this allows wasm-mutate to be used as a test case reducer. shrink it down until the bug is the only thing left standing. ✂️🔥
• -h, --help — print help (see a summary with -h). when in doubt, ask the tool itself. it's very forthcoming. 💖

---

⚠️ okay one gentle heads-up: exit code 3 is the one that sneaks up on you, because it only happens when the seed and your constraints genuinely can't produce a mutation. it happens rarely with reasonable constraints—so try again with a new seed or loosen your constraints. do NOT sit there rerunning the same seed and expecting a different answer, that's not how any of this works bestie 😭

also remember --generate-dwarf genuinely does nothing if your INPUT is already a WebAssembly binary, or if the text format uses (module binary ...). no effect means no effect. don't fight it. 💅

---

and that's the whole page!! go mutate something (responsibly) and remember: every weird module it spits out is just enrichment for your parser. 🦋✨

this was wasm-tools mutate, version 1.239.0+ds, from August 2026, one (1) of the User Commands in section 1 of the manual. mwah. 💜 no cap, you're gonna slay at fuzzing now. periodt. 🎀💖