Skip to content

Commit 527fe85

Browse files
committed
docs: showcase the mutation framework in the readme
1 parent 82b404d commit 527fe85

File tree

1 file changed

+15
-21
lines changed

1 file changed

+15
-21
lines changed

README.md

Lines changed: 15 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -23,13 +23,10 @@
2323
</div>
2424

2525
> [!IMPORTANT]
26-
> Hello users!
26+
> **Jazzer** is back under the **Apache 2.0 license**!
2727
>
28-
> We are thrilled to announce that **Jazzer** is now back under the **Apache 2.0 license**!
29-
>
30-
> A year ago, we temporarily stopped maintaining Jazzer as open source.
31-
> During this time, we received incredible feedback, support, and ideas from
32-
> the community, which motivated us to find a way to bring Jazzer back to the
28+
> We previously paused open-source maintenance but the incredible feedback, support, and ideas from
29+
> the community motivated us to find a way to bring Jazzer back to the
3330
> open-source world.
3431
>
3532
> Thanks to your enthusiasm and contributions, and a special callout to the
@@ -57,28 +54,27 @@ The following steps assume that JUnit 5.9.0 or higher is set up for your project
5754
1. Add a dependency on `com.code-intelligence:jazzer-junit:<latest version>`.
5855
All Jazzer Maven artifacts are signed with [this key](deploy/maven.pub).
5956
2. Add a new *fuzz test* to a new or existing test class: a method annotated with [`@FuzzTest`](https://codeintelligencetesting.github.io/jazzer-docs/jazzer-junit/com/code_intelligence/jazzer/junit/FuzzTest.html) and at least one parameter.
60-
Using a single parameter of type [`FuzzedDataProvider`](https://codeintelligencetesting.github.io/jazzer-docs/jazzer-api/com/code_intelligence/jazzer/api/FuzzedDataProvider.html), which provides utility functions to produce commonly used Java values, or `byte[]` is recommended for optimal performance and reproducibility of findings.
57+
A list of supported parameter types can be found in the [documentation](docs/junit-integration.md#supported-types).
6158
3. Assuming your test class is called `com.example.MyFuzzTests`, create the *inputs directory* `src/test/resources/com/example/MyFuzzTestsInputs`.
6259
4. Run a fuzz test with the environment variable `JAZZER_FUZZ` set to `1` to let the fuzzer rapidly try new sets of arguments.
6360
If the fuzzer finds arguments that make your fuzz test fail or even trigger a security issue, it will store them in the inputs directory.
6461
In this mode, only a single fuzz test is executed per test run (see [#599](https://github.com/CodeIntelligenceTesting/jazzer/issues/599) for details).
6562
5. Run the fuzz test without `JAZZER_FUZZ` set to execute it only on the inputs in the inputs directory.
6663
This mode, which behaves just like a traditional unit test, ensures that issues previously found by the fuzzer remain fixed and can also be used to debug the fuzz test on individual inputs.
6764

68-
A simple property-based fuzz test could look like this (excluding imports):
65+
A simple property-based fuzz test could look like this:
6966

7067
```java
7168
class ParserTests {
72-
@Test
73-
void unitTest() {
74-
assertEquals("foobar", SomeScheme.decode(SomeScheme.encode("foobar")));
75-
}
76-
77-
@FuzzTest
78-
void fuzzTest(FuzzedDataProvider data) {
79-
String input = data.consumeRemainingAsString();
80-
assertEquals(input, SomeScheme.decode(SomeScheme.encode(input)));
81-
}
69+
@Test
70+
void unitTest() {
71+
assertEquals("foobar", SomeScheme.decode(SomeScheme.encode("foobar")));
72+
}
73+
74+
@FuzzTest
75+
void fuzzTest(@NotNull String input) {
76+
assertEquals(input, SomeScheme.decode(SomeScheme.encode(input)));
77+
}
8278
}
8379
```
8480

@@ -91,7 +87,7 @@ A detailed description of the JUnit integration can be found in the [documentati
9187
You can also use GitHub release archives to run a standalone Jazzer binary that starts its own JVM configured for fuzzing:
9288

9389
1. Download and extract the latest release from the [GitHub releases page](https://github.com/CodeIntelligenceTesting/jazzer/releases).
94-
2. Add a new class to your project with a <code>public static void fuzzerTestOneInput(<a href="https://codeintelligencetesting.github.io/jazzer-docs/jazzer-api/com/code_intelligence/jazzer/api/FuzzedDataProvider.html">FuzzedDataProvider</a> data)</code> method.
90+
2. Add a new class to your project with a <code>public static void fuzzerTestOneInput(String par1, int par2, int[] par3, ...)</code> method, with the parameters you want to use in the fuzz test.
9591
3. Compile your fuzz test with `jazzer_standalone.jar` on the classpath.
9692
4. Run the `jazzer` binary (`jazzer.exe` on Windows), specifying the classpath and fuzz test class:
9793

@@ -146,5 +142,3 @@ Previously, Jazzer used AFL-style coverage instrumentation as pioneered by [keli
146142
<p align="center">
147143
<a href="https://www.code-intelligence.com"><img src="https://www.code-intelligence.com/hubfs/Logos/CI%20Logos/CI_Header_GitHub_quer.jpeg" height=50px alt="Code Intelligence logo"></a>
148144
</p>
149-
150-
[`FuzzedDataProvider`]: https://codeintelligencetesting.github.io/jazzer-docs/jazzer-api/com/code_intelligence/jazzer/api/FuzzedDataProvider.html

0 commit comments

Comments
 (0)