From 959fb52b5be64c7b39b7e6898e8f8b38c5e50be8 Mon Sep 17 00:00:00 2001
From: Nicolas DUBIEN <dubzzz@users.noreply.github.com>
Date: Wed, 9 May 2018 20:37:14 +0200
Subject: [PATCH] Update README.md

---
 README.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)

diff --git a/README.md b/README.md
index 3cb562c7f8a..cd6b302c17d 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,10 @@
 - [Properties](#properties)
 - [Runners](#runners)
 
+[Tips](#tips)
+- [Preview generated values](#preview-generated-values)
+- [Replay after failure](#replay-after-failure)
+
 [Issues found by fast-check in famous packages](#issues-found-by-fast-check-in-famous-packages)
 
 [Examples](https://github.com/dubzzz/fast-check/tree/master/example) - [Examples against REST API](https://github.com/dubzzz/fuzz-rest-api) - [More examples](https://github.com/dubzzz/fast-check-examples)
@@ -381,6 +385,74 @@ function statistics<Ts>(generator: Generator<Ts>, classify: Classifier<Ts>, para
 function statistics<Ts>(generator: Generator<Ts>, classify: Classifier<Ts>, numGenerated: number): void;
 ```
 
+## Tips
+
+### Preview generated values
+
+Before writing down your test, it might be great to confirm that the arbitrary you will be using produce the values you want.
+
+This can be done very easily by using either `fc.sample` or `fc.statistics`.
+
+The following code constructs an array containing the first 10 values that would have been generated by the arbitrary `fc.anything()` if used inside a `fc.assert` or `fc.check`:
+
+```typescript
+fc.sample(
+    fc.anything(), // arbitrary or property to extract the values from
+    10             // number of values to extract
+);
+```
+
+In some cases, having a sample is not enough and we want more insights about the generated data.
+For instance, I might be interested by the share of even numbers generated by `fc.nat()`.
+For that purpose I can use `fc.statistics` as follow:
+
+```typescript
+fc.statistics(
+    fc.nat(),    // arbitrary or property to extract the values from
+    n => n % 2 === 0 ? 'Even number' : 'Odd number', // classifier
+    10000        // number of values to extract
+);
+// Possible output (console.log):
+// Odd number...50.30%
+// Even number..49.70%
+```
+
+### Replay after failure
+
+`fast-check` comes with a must have feature: replay a failing case immediately given its seed and path (seed only to replay all).
+
+Whenever `fc.assert` encounters a failure, it displays an error log featuring both the seed and the path to replay it. For instance, in the output below the seed is 1525890375951 and the path 0:0.
+
+```
+Error: Property failed after 1 tests (seed: 1525890375951, path: 0:0): [0]
+Shrunk 1 time(s)
+Got error: Property failed by returning false
+```
+
+In order to replay the failure on the counterexample - `[0]`, you have to change your code as follow:
+
+```typescript
+// Original code
+fc.assert(
+  fc.property(
+    fc.nat(),
+    checkEverythingIsOk
+  )
+);
+
+// Replay code: straight to the minimal counterexample
+fc.assert(
+  fc.property(
+    fc.nat(),
+    checkEverythingIsOk
+  ),
+  {
+    seed: 1525890375951,
+    path: "0:0"
+  }
+);
+```
+
 ## Issues found by fast-check in famous packages
 
 `fast-check` has been able to find some unexpected behaviour among famous npm packages. Here are some of the errors detected using `fast-check`: