You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
+9-9
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Breaking your Rust code for fun & profit
2
2
3
-
*this is a architecture-preview, not all components are there*
3
+
*this is an architecture-preview, not all components are there*
4
4
5
5
This is a mutation testing framework for Rust code.
6
6
@@ -15,15 +15,15 @@ The difference to line or branch coverage is that those measure if the code unde
15
15
16
16
`mutagen`'s core functionality is implemented via a procedural macro that transforms the source code. Known patterns of code are replaced by mutators with identical behavior unless activated. Activating a mutator at runtime alters its behavior - having the effect of a mutation.
17
17
18
-
The procedural macro has access the bare AST. Information about inferred types, implemented traits, control flow, data flow or signatures of other functions are not available during the execution of procedural macros. Therefore, the mutations must be possible without additional type-information.
18
+
The procedural macro has access to the bare AST. Information about inferred types, implemented traits, control flow, data flow or signatures of other functions are not available during the execution of procedural macros. Therefore, the mutations must be possible without additional type-information.
19
19
20
20
In order to be fast, it is necessary that the compilation of the test suite is performed only once. To achieve this, all mutations are baked into the code once and are selected at runtime via an environment variable. This means the mutations are not allowed to produce code that fails to compile.
21
21
22
22
This project is basically an experiment to see what mutations we can still apply under those constraints.
23
23
24
24
## Using mutagen
25
25
26
-
**Note**: The version of mutagen (`0.2.0`) referenced in this README is not yet released on `crates.io`. To install and use an earlier, released version, you can follow the instructions on [crates.io mutagen crate](https://crates.io/crates/mutagen).
26
+
**Note**: The version of `mutagen` (`0.2.0`) referenced in this README is not yet released on `crates.io`. To install and use an earlier, released version, you can follow the instructions on [crates.io mutagen crate](https://crates.io/crates/mutagen).
27
27
28
28
You need Rust nightly to compile the procedural macro.
29
29
@@ -41,7 +41,7 @@ To use the attribute `#[mutate]`, you need to import it.
41
41
usemutagen::mutate;
42
42
```
43
43
44
-
Now you can advise mutagen to mutate any function or method by prepending `#[cfg_attr(test, mutate)]`. The use of `cfg_attr` ensures the `#[mutate]` attribute will only be active in test mode. The repository contains an example that shows how mutagen could be used.
44
+
Now you can advise `mutagen` to mutate any function or method by prepending `#[cfg_attr(test, mutate)]`. The use of `cfg_attr` ensures the `#[mutate]` attribute will only be active in test mode. The repository contains an example that shows how `mutagen` could be used.
45
45
46
46
### Running mutagen
47
47
@@ -50,13 +50,13 @@ Install `cargo-mutagen`, which can be done by running `cargo install cargo-mutag
50
50
The mutants can also be run manually: `cargo test` will compile code and write the performed mutations to `target/mutagen/mutations`. This file contains ids and descriptions of possible mutations.
51
51
Then, the environment variable `MUTATION_ID` can be used to activate a single mutation as defined by the `mutations` file. The environment variable can be set before calling the test suite, i.e. `MUTATION_ID=1 cargo test`, `MUTATION_ID=2 ..`, etc. For every mutation count at of least one, the test suite should fail
52
52
53
-
You can run `cargo mutagen -- --coverage` in order to reduce the time it takes to run the mutated code. When running on this mode, it runs the test suite at the beginning of the process and checks which tests are hitting mutated code. Then, for each mutation, instead of running the whole test suite again, it executes only the tests that are affected by the current mutation. This mode is specially useful when the test suite is slow or when the mutated code affects a little part of it.
53
+
You can run `cargo mutagen -- --coverage` in order to reduce the time it takes to run the mutated code. When running in this mode, it runs the test suite at the beginning of the process and checks which tests are hitting mutated code. Then, for each mutation, instead of running the whole test suite again, it executes only the tests that are affected by the current mutation. This mode is especially useful when the test suite is slow or when the mutated code affects a little part of it.
54
54
55
55
If you referenced `mutagen` in your cargo.toml via the git repository as noted in the `Using Mutagen` section, you will probably want to install the development version of `cargo-mutagen`. To install the development version, run `cargo install` in the `mutagen-runner` dir of this repository. Running `cargo install --force` might be necessary to overwrite any existing `cargo-mutagen` binary.
56
56
57
57
## A Word of Warning
58
58
59
-
Mutagen will change the code you annotate with the `#[mutate]` attribute. This can have dire consequences in some cases. However, functions not annotated with `#[mutate]` will not be altered.
59
+
`mutagen` will change the code you annotate with the `#[mutate]` attribute. This can have dire consequences in some cases. However, functions not annotated with `#[mutate]` will not be altered.
60
60
61
61
*Do not use `#[mutate]` for code that can cause damage if buggy*. By corrupting the behavior or sanity checks of some parts of the program, dangerous accidents can happen. For example by overwriting the wrong file or sending credentials to the wrong server.
62
62
@@ -66,11 +66,11 @@ Mutagen will change the code you annotate with the `#[mutate]` attribute. This c
66
66
67
67
## Limitations of Mutations
68
68
69
-
*No mutations will be introduced in `unsafe`-blocks and `unsafe` functions*. Mutations would probably break the some invariantes. Moreover, mutations in unsafe code could lead to undefined behavior that cannot be observed by any testcase.
69
+
*No mutations will be introduced in `unsafe`-blocks and `unsafe` functions*. Such mutations would probably break some invariants. Moreover, mutations in unsafe code could lead to undefined behavior that cannot be observed by any testcase.
70
70
71
-
*`const` and `static` expressions cannot be mutated.* They are evaluated at compile-time and Mutagen can only affect code that can alter its behavior at run-time. Array lengths and global constants are examples of `const` expressions.
71
+
*`const` and `static` expressions cannot be mutated.* They are evaluated at compile-time and `mutagen` can only affect code that can alter its behavior at run-time. Array lengths and global constants are examples of `const` expressions.
72
72
73
-
*Patterns are cannot mutated.* Mutations are introduced by injecting calls to mutagen-internal functions, which cannot be placed inside patterns.
73
+
*Patterns cannot be mutated.* Mutations are introduced by injecting calls to mutagen-internal functions, which cannot be placed inside patterns.
0 commit comments