Refactor Flowtype definition

Minor syntactical changes aside, it's now equivalent to the TypeScript
definition!

Author: novemberborn

docs/recipes/flow.md

@@ -0,0 +1,82 @@
+# Flow
+
+Translations: [Español](https://github.com/avajs/ava-docs/blob/master/es_ES/docs/recipes/typescript.md), [Français](https://github.com/avajs/ava-docs/blob/master/fr_FR/docs/recipes/typescript.md), [Italiano](https://github.com/avajs/ava-docs/blob/master/it_IT/docs/recipes/typescript.md), [Русский](https://github.com/avajs/ava-docs/blob/master/ru_RU/docs/recipes/typescript.md), [简体中文](https://github.com/avajs/ava-docs/blob/master/zh_CN/docs/recipes/typescript.md)
+
+AVA comes bundled with a Flow definition file. This allows developers to leverage Flow for writing tests.
+
+This guide assumes you've already set up Flow for your project. Note that AVA's definition as been tested with version 0.64.
+
+> TODO: Best practices for stripping the flow types when running the tests.
+
+## Writing tests
+
+Create a `test.js` file.
+
+```js
+// @flow
+import test from 'ava';
+
+const fn = async () => Promise.resolve('foo');
+
+test(async (t) => {
+	t.is(await fn(), 'foo');
+});
+```
+
+## Typing [`t.context`](https://github.com/avajs/ava#test-context)
+
+By default, the type of `t.context` will be [`any`](https://www.typescriptlang.org/docs/handbook/basic-types.html#any). AVA exposes an interface `TestInterface<Context>` which you can use to apply your own type to `t.context`. This can help you catch errors at compile-time:
+
+```js
+// @flow
+import anyTest, {TestInterface} from 'ava';
+import type {TestInterface} from 'ava';
+
+const test: TestInterface<{foo: string}> = anyTest;
+
+test.beforeEach(t => {
+	t.context = {foo: 'bar'};
+});
+
+test.beforeEach(t => {
+	t.context.foo = 123; // error:  Type '123' is not assignable to type 'string'
+});
+
+test.serial.cb.failing('very long chains are properly typed', t => {
+	t.context.fooo = 'a value'; // error: Property 'fooo' does not exist on type ''
+});
+
+test('an actual test', t => {
+	t.deepEqual(t.context.foo.map(c => c), ['b', 'a', 'r']); // error: Property 'map' does not exist on type 'string'
+});
+```
+
+Note that `t.context` is `null` unless it's assigned. You'll have to guard against this to avoid Flow errors:
+
+```ts
+import anyTest, {TestInterface} from 'ava';
+
+const test: TestInterface<{foo: string}> = anyTest;
+
+test.beforeEach(t => {
+	t.context = {foo: 'bar'};
+});
+
+test('foo is bar', t => {
+	t.context && t.is(t.context.foo, 'bar');
+});
+```
+
+## Using `t.throws()` and `t.notThrows()`
+
+The `t.throws()` and `t.noThrows()` assertions can be called with a function that returns an observable or a promise. You may have to explicitly type functions that have no return value:
+
+```ts
+import test from 'ava';
+
+test('just throws', t => {
+	const expected = new Error();
+	const err = t.throws((): void => { throw expected; });
+	t.is(err, expected);
+});
+```