Document fc.context

Fxes #156

README.md

@@ -95,6 +95,7 @@ fast-check has initially been designed in an attempt to cope with limitations I
 - replay directly on the minimal counterexample - *no need to replay the whole sequence, you get directly the counterexample*
 - custom examples in addition of generated ones - *no need to duplicate the code to play the property on custom examples*
 - model based approach - *use the power of property based testing to test UI, APIs or state machines*
+- logger per predicate run - *simplify your troubleshoot with fc.context and its logging feature*
 
 For more details, refer to the documentation in the links above.
 

documentation/Arbitraries.md

@@ -101,6 +101,10 @@ Default for `values` are: `fc.boolean()`, `fc.integer()`, `fc.double()`, `fc.str
 - `compareFunc()` generate a comparison function taking two parameters `a` and `b` and producing an integer value. Output is zero when `a` and `b` are considered to be equivalent. Output is strictly inferior to zero means that `a` should be considered strictly inferior to `b` (similar for strictly superior to zero)
 - `func(arb: Arbitrary<TOut>)` generate a function of type `(...args: TArgs) => TOut` outputing values generated using `arb`
 
+## Extended tools
+
+- `context()` generate a `Context` instance for each predicate run. `Context` can be used to log stuff within the run itself. In case of failure, the logs will be attached in the counterexample and visible in the stack trace
+
 ## Model based testing
 
 Model based testing approach extends the power of property based testing to state machines - *eg.: UI, data-structures*.

documentation/Tips.md

@@ -164,6 +164,29 @@ Encountered failures were:
 
 With that output, we notice that our `contains` implementation seems to fail when the `pattern` we are looking for is the beginning of the string we are looking in.
 
+## Log within a predicate
+
+In order to ease the diagnosis of red properties, fast-check introduced an internal logger that can be used to log stuff inside the predicate itself.
+
+The advantage of this logger is that one logger is linked to one run so that the counterexample comes with its own logs (and not the ones of previous failures leading to this counterexample). Logs will only be shown in case of failure contrary to `console.log` that would pop everywhere.
+
+Usage is quite simple, logger is one of the features available inside the `Context` interface:
+
+```typescript
+fc.assert(
+    fc.property(
+        fc.string(),
+        fc.string(),
+        fc.context(), // comes with a log method
+        (a: number, b: number, ctx: fc.Context): boolean => {
+            const intermediateResult = /* ... */;
+            ctx.log(`Intermediate: ${intermediateResult}`);
+            return check(intermediateResult);
+        }
+    )
+)
+```
+
 ## 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.