Assert that async expects are awaited or returned - Closes #54, #254

docs/rules/valid-expect.md

@@ -20,8 +20,56 @@ or when a matcher function was not called, e.g.:
 expect(true).toBeDefined;
 ```
 
+or when an async assertion was not `await`ed or returned, e.g.:
+
+```js
+expect(Promise.resolve('Hi!')).resolves.toBe('Hi!');
+```
+
 This rule is enabled by default.
 
+## Options
+
+```js
+{
+  type: 'object',
+  properties: {
+    alwaysAwait: {
+      type: 'boolean',
+      default: false,
+    },
+  },
+  additionalProperties: false,
+}
+```
+
+### `alwaysAwait`
+
+Enforces to use `await` inside block statements. Using `return` will trigger a
+warning. Returning one line statements with arrow functions is _always allowed_.
+
+Examples of **incorrect** code for the { "alwaysAwait": **true** } option:
+
+```js
+// alwaysAwait: true
+test('test1', async () => {
+  await expect(Promise.resolve(2)).resolves.toBeDefined();
+  return expect(Promise.resolve(1)).resolves.toBe(1); // `return` statement will trigger a warning
+});
+```
+
+Examples of **correct** code for the { "alwaysAwait": **true** } option:
+
+```js
+// alwaysAwait: true
+test('test1', async () => {
+  await expect(Promise.resolve(2)).resolves.toBeDefined();
+  await expect(Promise.resolve(1)).resolves.toBe(1);
+});
+
+test('test2', () => expect(Promise.resolve(2)).resolves.toBe(2));
+```
+
 ### Default configuration
 
 The following patterns are considered warnings:
@@ -33,6 +81,12 @@ expect('something', 'else');
 expect('something');
 expect(true).toBeDefined;
 expect(Promise.resolve('hello')).resolves;
+expect(Promise.resolve('hello')).resolves.toEqual('hello');
+Promise.resolve(expect(Promise.resolve('hello')).resolves.toEqual('hello'));
+Promise.all([
+  expect(Promise.resolve('hello')).resolves.toEqual('hello'),
+  expect(Promise.resolve('hi')).resolves.toEqual('hi'),
+]);
 ```
 
 The following patterns are not warnings:
@@ -41,5 +95,12 @@ The following patterns are not warnings:
 expect('something').toEqual('something');
 expect([1, 2, 3]).toEqual([1, 2, 3]);
 expect(true).toBeDefined();
-expect(Promise.resolve('hello')).resolves.toEqual('hello');
+await expect(Promise.resolve('hello')).resolves.toEqual('hello');
+await Promise.resolve(
+  expect(Promise.resolve('hello')).resolves.toEqual('hello'),
+);
+await Promise.all(
+  expect(Promise.resolve('hello')).resolves.toEqual('hello'),
+  expect(Promise.resolve('hi')).resolves.toEqual('hi'),
+);
 ```