third_party/rust/wasm-smith/README.md

   1 # `wasm-smith`
   2
   3 **A WebAssembly test case generator.**
   4
   5 [![](https://docs.rs/wasm-smith/badge.svg)](https://docs.rs/wasm-smith/)
   6 [![](https://img.shields.io/crates/v/wasm-smith.svg)](https://crates.io/crates/wasm-smith)
   7 [![](https://img.shields.io/crates/d/wasm-smith.svg)](https://crates.io/crates/wasm-smith)
   8
   9 * [Features](#features)
  10 * [Usage](#usage)
  11   * [With `cargo fuzz` and `libfuzzer-sys`](#with-cargo-fuzz-and-libfuzzer-sys)
  12   * [As a Command Line Tool](#as-a-command-line-tool)
  13
  14 ## Features
  15
  16 * **Always valid:** All generated Wasm modules pass validation. `wasm-smith`
  17   gets past your wasm parser and validator, exercising the guts of your Wasm
  18   compiler, runtime, or tool.
  19
  20 * **Supports the full WebAssembly language:** Doesn't have blind spots or
  21   unimplemented instructions.
  22
  23 * **Implements the
  24   [`Arbitrary`](https://docs.rs/arbitrary/*/arbitrary/trait.Arbitrary.html)
  25   trait**: Easy to use with [`cargo
  26   fuzz`](https://github.com/rust-fuzz/cargo-fuzz) and
  27   [`libfuzzer-sys`](https://github.com/rust-fuzz/libfuzzer)!
  28
  29 * **Deterministic:** Given the same input seed, always generates the same output
  30   Wasm module, so you can always reproduce test failures.
  31
  32 * **Plays nice with mutation-based fuzzers:** Small changes to the input tend to
  33   produce small changes to the output Wasm module. Larger inputs tend to
  34   generate larger Wasm modules.
  35
  36 ## Usage
  37
  38 ### With `cargo fuzz` and `libfuzzer-sys`
  39
  40 First, use `cargo fuzz` to define a new fuzz target:
  41
  42 ```shell
  43 $ cargo fuzz add my_wasm_smith_fuzz_target
  44 ```
  45
  46 Next, add `wasm-smith` to your dependencies:
  47
  48 ```shell
  49 $ cargo add wasm-smith
  50 ```
  51
  52 Then, define your fuzz target so that it takes arbitrary `wasm_smith::Module`s
  53 as an argument, convert the module into serialized Wasm bytes via the `to_bytes`
  54 method, and then feed it into your system:
  55
  56 ```rust
  57 // fuzz/fuzz_targets/my_wasm_smith_fuzz_target.rs
  58
  59 #![no_main]
  60
  61 use libfuzzer_sys::fuzz_target;
  62 use wasm_smith::Module;
  63
  64 fuzz_target!(|module: Module| {
  65     let wasm_bytes = module.to_bytes();
  66
  67     // Your code here...
  68 });
  69 ```
  70
  71 Finally, start fuzzing:
  72
  73 ```shell
  74 $ cargo fuzz run my_wasm_smith_fuzz_target
  75 ```
  76
  77 > **Note:** Also check out [the `validate` fuzz
  78 > target](https://github.com/bytecodealliance/wasm-tools/blob/main/fuzz/src/validate.rs)
  79 > defined in this repository. Using the `wasmparser` crate, it checks that every
  80 > module generated by `wasm-smith` validates successfully.
  81
  82 ### As a Command Line Tool
  83
  84 Install the CLI tool via `cargo`:
  85
  86 ```shell
  87 $ cargo install wasm-tools
  88 ```
  89
  90 Convert some arbitrary input into a valid Wasm module:
  91
  92 ```shell
  93 $ head -c 100 /dev/urandom | wasm-tools smith -o test.wasm
  94 ```
  95
  96 Finally, run your tool on the generated Wasm module:
  97
  98 ```shell
  99 $ my-wasm-tool test.wasm
 100 ```