feat(rule): add valid-describe rule

Resolves jest-community#18

README.md

@@ -88,6 +88,7 @@ for more information about extending configuration files.
 | [prefer-to-be-null](docs/rules/prefer-to-be-null.md)               | Suggest using `toBeNull()`                                      |                                                                         | ![fixable](https://img.shields.io/badge/-fixable-green.svg) |
 | [prefer-to-be-undefined](docs/rules/prefer-to-be-undefined.md)     | Suggest using `toBeUndefined()`                                 |                                                                         | ![fixable](https://img.shields.io/badge/-fixable-green.svg) |
 | [prefer-expect-assertions](docs/rules/prefer-expect-assertions.md) | Suggest using `expect.assertions()` OR `expect.hasAssertions()` |                                                                         |                                                             |
+| [valid-describe](docs/rules/valid-describe.md)                     | Enforce valid `describe()` callback                             |                                                                         |                                                             |
 | [valid-expect](docs/rules/valid-expect.md)                         | Enforce valid `expect()` usage                                  | ![recommended](https://img.shields.io/badge/-recommended-lightgrey.svg) |                                                             |
 | [valid-expect-in-promise](docs/rules/valid-expect-in-promise.md)   | Enforce having return statement when testing with promises      |                                                                         |                                                             |
 

docs/rules/valid-describe.md

@@ -0,0 +1,53 @@
+# Enforce valid `describe()` callback (valid-describe)
+
+Using an improper `describe()` callback function can lead to unexpected test errors.
+
+## Rule Details
+
+This rule validates that the second parameter of a `describe()` function is a callback function. This callback function:
+
+* should not be [async](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function)
+* should not contain any parameters
+* should not contain any `return` statements
+
+The following `describe` function aliases are also validated:
+
+* `describe`
+* `describe.only`
+* `describe.skip`
+* `fdescribe`
+* `xdescribe`
+
+The following patterns are considered warnings:
+
+```js
+// Async callback functions are not allowed
+describe('myFunction()', async () => {
+  // ...
+});
+
+// Callback function parameters are not allowed
+describe('myFunction()', done => {
+  // ...
+});
+
+//
+describe('myFunction', () => {
+  // No return statements are allowed in block of a callback function
+  return Promise.resolve().then(() => {
+    it('breaks', () => {
+      throw new Error('Fail');
+    });
+  });
+});
+```
+
+The following patterns are not considered warnings:
+
+```js
+describe('myFunction()', () => {
+  it('returns a truthy value', () => {
+    expect(myFunction()).toBeTruthy();
+  });
+});
+```

index.js

@@ -7,6 +7,7 @@ const noLargeSnapshots = require('./rules/no_large_snapshots');
 const preferToBeNull = require('./rules/prefer_to_be_null');
 const preferToBeUndefined = require('./rules/prefer_to_be_undefined');
 const preferToHaveLength = require('./rules/prefer_to_have_length');
+const validDescribe = require('./rules/valid-describe');
 const validExpect = require('./rules/valid_expect');
 const preferExpectAssertions = require('./rules/prefer_expect_assertions');
 const validExpectInPromise = require('./rules/valid_expect_in_promise');
@@ -63,6 +64,7 @@ module.exports = {
     'prefer-to-be-null': preferToBeNull,
     'prefer-to-be-undefined': preferToBeUndefined,
     'prefer-to-have-length': preferToHaveLength,
+    'valid-describe': validDescribe,
     'valid-expect': validExpect,
     'prefer-expect-assertions': preferExpectAssertions,
     'valid-expect-in-promise': validExpectInPromise,

rules/__tests__/valid-describe.test.js

@@ -0,0 +1,185 @@
+'use strict';
+
+const RuleTester = require('eslint').RuleTester;
+const rules = require('../..').rules;
+
+const ruleTester = new RuleTester({
+  parserOptions: {
+    ecmaVersion: 8,
+  },
+});
+
+ruleTester.run('valid-describe', rules['valid-describe'], {
+  valid: [
+    'describe("foo")',
+    'describe("foo", function() {})',
+    'describe("foo", () => {})',
+    'xdescribe("foo", () => {})',
+    'fdescribe("foo", () => {})',
+    'describe.only("foo", () => {})',
+    'describe.skip("foo", () => {})',
+    `
+    describe('foo', () => {
+      it('bar', () => {
+        return Promise.resolve(42).then(value => {
+          expect(value).toBe(42)
+        })
+      })
+    })
+    `,
+    `
+    describe('foo', () => {
+      it('bar', async () => {
+        expect(await Promise.resolve(42)).toBe(42)
+      })
+    })
+    `,
+  ],
+  invalid: [
+    {
+      code: 'describe("foo", async () => {})',
+      errors: [{ message: 'No async describe callback', line: 1, column: 17 }],
+    },
+    {
+      code: 'describe("foo", async function () {})',
+      errors: [{ message: 'No async describe callback', line: 1, column: 17 }],
+    },
+    {
+      code: 'xdescribe("foo", async function () {})',
+      errors: [{ message: 'No async describe callback', line: 1, column: 18 }],
+    },
+    {
+      code: 'fdescribe("foo", async function () {})',
+      errors: [{ message: 'No async describe callback', line: 1, column: 18 }],
+    },
+    {
+      code: 'describe.only("foo", async function () {})',
+      errors: [{ message: 'No async describe callback', line: 1, column: 22 }],
+    },
+    {
+      code: 'describe.skip("foo", async function () {})',
+      errors: [{ message: 'No async describe callback', line: 1, column: 22 }],
+    },
+    {
+      code: `
+      describe('sample case', () => {
+        it('works', () => {
+          expect(true).toEqual(true);
+        });
+        describe('async', async () => {
+          await new Promise(setImmediate);
+          it('breaks', () => {
+            throw new Error('Fail');
+          });
+        });
+      });`,
+      errors: [{ message: 'No async describe callback', line: 6, column: 27 }],
+    },
+    {
+      code: `
+      describe('foo', function () {
+        return Promise.resolve().then(() => {
+          it('breaks', () => {
+            throw new Error('Fail')
+          })
+        })
+      })
+      `,
+      errors: [
+        {
+          message: 'Unexpected return statement in describe callback',
+          line: 3,
+          column: 9,
+        },
+      ],
+    },
+    {
+      code: `
+      describe('foo', () => {
+        return Promise.resolve().then(() => {
+          it('breaks', () => {
+            throw new Error('Fail')
+          })
+        })
+        describe('nested', () => {
+          return Promise.resolve().then(() => {
+            it('breaks', () => {
+              throw new Error('Fail')
+            })
+          })
+        })
+      })
+      `,
+      errors: [
+        {
+          message: 'Unexpected return statement in describe callback',
+          line: 3,
+          column: 9,
+        },
+        {
+          message: 'Unexpected return statement in describe callback',
+          line: 9,
+          column: 11,
+        },
+      ],
+    },
+    {
+      code: `
+      describe('foo', async () => {
+        await something()
+        it('does something')
+        describe('nested', () => {
+          return Promise.resolve().then(() => {
+            it('breaks', () => {
+              throw new Error('Fail')
+            })
+          })
+        })
+      })
+      `,
+      errors: [
+        {
+          message: 'No async describe callback',
+          line: 2,
+          column: 23,
+        },
+        {
+          message: 'Unexpected return statement in describe callback',
+          line: 6,
+          column: 11,
+        },
+      ],
+    },
+    {
+      code: 'describe("foo", done => {})',
+      errors: [
+        {
+          message: 'Unexpected argument in describe callback',
+          line: 1,
+          column: 17,
+        },
+      ],
+    },
+    {
+      code: 'describe("foo", function (done) {})',
+      errors: [
+        {
+          message: 'Unexpected argument in describe callback',
+          line: 1,
+          column: 27,
+        },
+      ],
+    },
+    {
+      code: 'describe("foo", async function (done) {})',
+      errors: [
+        { message: 'No async describe callback', line: 1, column: 17 },
+        {
+          message: 'Unexpected argument in describe callback',
+          line: 1,
+          column: 33,
+        },
+      ],
+    },
+  ],
+});

rules/valid-describe.js

@@ -0,0 +1,66 @@
+'use strict';
+
+const describeAliases = Object.assign(Object.create(null), {
+  describe: true,
+  'describe.only': true,
+  'describe.skip': true,
+  fdescribe: true,
+  xdescribe: true,
+});
+
+const getNodeName = node => {
+  if (node.type === 'MemberExpression') {
+    return node.object.name + '.' + node.property.name;
+  }
+  return node.name;
+};
+
+const isDescribe = node =>
+  node.type === 'CallExpression' && describeAliases[getNodeName(node.callee)];
+
+const isFunction = node =>
+  node.type === 'FunctionExpression' || node.type === 'ArrowFunctionExpression';
+
+const isAsync = node => node.async;
+
+const hasParams = node => node.params.length > 0;
+
+module.exports = {
+  meta: {
+    docs: {
+      url:
+        'https://github.com/jest-community/eslint-plugin-jest/blob/master/docs/rules/valid-describe.md',
+    },
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (node && isDescribe(node)) {
+          const callbackFunction = node.arguments[1];
+          if (callbackFunction && isFunction(callbackFunction)) {
+            if (isAsync(callbackFunction)) {
+              context.report({
+                message: 'No async describe callback',
+                node: callbackFunction,
+              });
+            }
+            if (hasParams(callbackFunction)) {
+              context.report({
+                message: 'Unexpected argument in describe callback',
+                node: callbackFunction.params[0],
+              });
+            }
+            callbackFunction.body.body.forEach(node => {
+              if (node.type === 'ReturnStatement') {
+                context.report({
+                  message: 'Unexpected return statement in describe callback',
+                  node: node,
+                });
+              }
+            });
+          }
+        }
+      },
+    };
+  },
+};