Docs for error-value

Author: sourcefrog

book/src/SUMMARY.md

@@ -15,6 +15,8 @@
   - [Listing and previewing mutations](list.md)
   - [Workspaces and packages](workspaces.md)
   - [Passing options to Cargo](cargo-args.md)
+- [Generating mutants](mutants.md)
+  - [Error values](error-values.md)
 - [Improving performance](performance.md)
   - [Parallelism](parallelism.md)
 - [Integrations](integrations.md)

book/src/error-values.md

@@ -0,0 +1,32 @@
+# Generating error values
+
+cargo-mutants can be configured to generate mutants that return an error value from functions that return a Result.
+
+This will flag cases where no test fails if the function returns an error: that might happen if there are _only_ tests for the error cases and not for the Ok case.
+
+Since crates can choose to use any type for their error values,
+cargo-mutants must be told how to construct an appropriate error.
+
+The `--error` command line option and the `error_value` configuration option specify an error value to use.
+
+These options can be repeated or combined, which might be useful
+if there are multiple error types in the crate. On any one mutation site, probably only one of the error values will be viable, and cargo-mutants will discover that and use it.
+
+The error value can be any Rust expression that evaluates to a value of the error type. It should not include the `Err` wrapper, because cargo-mutants will add that.
+
+For example, if your crate uses `anyhow::Error` as its error type, you might use `--error '::anyhow::anyhow!("error")'`.
+
+If you have your own error type, you might use `--error 'crate::MyError::Generic'`.
+
+Since the correct error type is a property of the source tree, the configuration should typically go into `.cargo/mutants.toml` rather than being specified on the command line:
+
+```toml
+error_values = ["::anyhow::anyhow!(\"mutated\")"]
+```
+
+To see only the mutants generated by this configuration, you
+can use a command like this:
+
+```sh
+cargo r mutants -F anyhow -vV -j4
+```

book/src/mutants.md

@@ -0,0 +1,27 @@
+# Generating mutants
+
+cargo mutants generates mutants by inspecting the existing
+source code and applying a set of rules to generate new code
+that is likely to compile but have different behavior.
+
+In the current release, the only mutation pattern is to
+replace function bodies with a value of the same type.
+This checks that the tests:
+
+1. Observe any side effects of the original function.
+2. Distinguish return values.
+
+More mutation rules will be added in future releases.
+
+| Return type | Mutation pattern |
+| ----------- | ---------------- |
+| `()`        | `()` (return unit, with no side effects) |
+| `bool`      | `true`, `false` |
+| `String`    | `String::new()`, `"xyzzy".into()` |
+| `Result`    | `Ok(Default::default())`, [and an error if configured](error-values.md) |
+| (any other) | `Default::default()` (and hope the type implements `Default`) |
+
+Some of these values may not be valid for all types: for example, returning
+`Default::default()` will work for many types, but not all. In this case the
+mutant is said to be "unviable": by default these are counted but not printed,
+although they can be shown with `--unviable`.