feat(rule): add eslint-plugin-mocha ☕️

Author: robertrossmann

README.md

@@ -6,6 +6,7 @@
 [flow-home]: https://flow.org
 [react-home]: http://reactjs.com
 [nodejs-home]: https://nodejs.org
+[mocha-home]: https://mochajs.org
 
 
 # JavaScript Coding Standards
@@ -62,6 +63,10 @@ See the [tutorial](tutorial) directory for lots of example config files.
 
 - @strv/javascript/environments/flow/recommended
 
+#### For [Mocha][mocha-home]
+
+- @strv/javascript/environments/mocha/recommended
+
 #### Coding styles
 
 These rulesets include rules which deal with how the code looks like and not how it works. They help keep the code clean and consistent.

environments/mocha/README.md

@@ -0,0 +1,11 @@
+# Mocha
+
+These configuration files are suitable to lint Mocha test files.
+
+## Configurations
+
+### @strv/javascript/environments/mocha/recommended
+
+Use this ruleset to configure ESLint to lint your Mocha test files. Mocha test files are by default identified by `*.test.*` or `*.spec.*` filenames or by being in the _test/_ directory in your project root.
+
+> ⚠️ You can use this environment ruleset in combination with any of the existing environment rulesets. Just make sure this one comes in as the last one.

environments/mocha/recommended.js

@@ -0,0 +1,73 @@
+/**
+ * Js-coding-standards
+ *
+ * @author      Robert Rossmann <rr.rossmann@me.com>
+ * @copyright   2018 STRV
+ * @license     http://choosealicense.com/licenses/bsd-3-clause  BSD-3-Clause License
+ */
+
+'use strict'
+
+const globs = require('../../globs')
+
+module.exports = {
+
+  overrides: [{
+    files: globs.test,
+
+    plugins: [
+      'mocha',
+    ],
+
+    env: {
+      mocha: true,
+    },
+
+    rules: {
+      // Enforces handling of callbacks for async tests
+      // Mocha allows you to write asynchronous tests by adding a done callback to the parameters of
+      // your test function. It is easy to forget calling this callback after the asynchronous
+      // operation is done.
+      // @TODO (semver-major): Raise to `error`
+      'mocha/handle-done-callback': 'warn',
+
+      // Limit the number of top-level suites in a single file
+      // This rule enforces having a limited amount of top-level suites in a file.
+      'mocha/max-top-level-suites': ['warn', { limit: 1 }],
+
+      // Disallow exclusive tests
+      // This rule reminds you to remove .only from your tests by raising a warning whenever you are
+      // using the exclusivity feature.
+      'mocha/no-exclusive-tests': 'warn',
+
+      // Disallow global tests
+      // This rule checks each mocha test function to not be located directly in the global scope.
+      'mocha/no-global-tests': 'warn',
+
+      // Disallow identical titles
+      // This rule looks at the title of every test and test suites. It will report when two test
+      // suites or two test cases at the same level of a test suite have the same title.
+      'mocha/no-identical-title': 'warn',
+
+      // Disallow tests to be nested within other tests
+      // This rule looks for all test cases (it, specify and test) or suites (describe, context and
+      // suite) which are nested within another test case.
+      // @TODO (semver-major): Raise to `error`
+      'mocha/no-nested-tests': 'warn',
+
+      // Disallow returning in a test or hook function that uses a callback
+      // Mocha's tests or hooks (like before) may be asynchronous by either returning a Promise or
+      // specifying a callback parameter for the function. It can be confusing to have both methods
+      // used in a test or hook, and from Mocha v3 on, causes the test to fail in order to force
+      // developers to remove this source of confusion.
+      // @TODO (semver-major): Raise to `error`
+      'mocha/no-return-and-callback': 'warn',
+
+      // Disallow setup in describe blocks
+      // Any setup directly in a describe is run before all tests execute. This rule reports all
+      // function calls and use of the dot operator (due to getters and setters) directly in
+      // describe blocks.
+      'mocha/no-setup-in-describe': 'warn',
+    },
+  }],
+}

environments/shared/recommended.js

@@ -223,43 +223,6 @@ module.exports = {
     // class, it will match to either ❇ (U+2747) or VARIATION SELECTOR-16 (U+FE0F) rather than ❇️.
     'no-misleading-character-class': 'error',
 
-    // Disallow certain object properties
-    // Currently configured for the following (more can be added as necessary):
-    // - Mocha test isolation features (skipping tests, running only certain tests)
-    'no-restricted-properties': ['warn', {
-      object: 'describe',
-      property: 'only',
-      message: 'Isolated test suite',
-    }, {
-      object: 'describe',
-      property: 'skip',
-      message: 'Skipped test suite. Use xdescribe() to write a pending test suite.',
-    }, {
-      object: 'it',
-      property: 'only',
-      message: 'Isolated test case',
-    }, {
-      object: 'it',
-      property: 'skip',
-      message: 'Skipped test case. Use xit() to write a pending test case.',
-    }, {
-      object: 'context',
-      property: 'only',
-      message: 'Isolated test suite',
-    }, {
-      object: 'context',
-      property: 'skip',
-      message: 'Skipped test suite. Use xcontext() to write a pending test suite.',
-    }, {
-      object: 'specify',
-      property: 'only',
-      message: 'Isolated test case',
-    }, {
-      object: 'specify',
-      property: 'skip',
-      message: 'Skipped test case. Use xspecify() to write a pending test case.',
-    }],
-
     // Disallow unnecessary `return await`
     // Inside an async function, return await is useless. Since the return value of an async
     // function is always wrapped in Promise.resolve, return await doesn’t actually do anything

package-lock.json

@@ -18,6 +18,7 @@
     "eslint-plugin-flowtype": "^2.39.1",
     "eslint-plugin-import": "^2.14.0",
     "eslint-plugin-jsx-a11y": "^6.1.1",
+    "eslint-plugin-mocha": "^5.2.0",
     "eslint-plugin-react": "^7.4.0"
   },
   "devDependencies": {

package.json

@@ -8,7 +8,7 @@ When configuring js-coding-standards, please keep the following in mind:
 - Always extend only from **one environment configuration** per _.eslintrc.js_
   > Some environment configuration files in this ruleset have conflicting rule configurations - you **will** experience weird issues if you include ie. both nodejs and react environments into a single _.eslintrc.js_ file.
   >
-  > If your project consists of both React and Node.js code, put them into separate folders and create _.eslintrc.js_ file for each of those folders.
+  > If your project consists of both React and Node.js code, you should utilise the `overrides` functionality in ESLint to only enable one environment ruleset for each type of code.
 
 - Do not include extensions when extending
   > You should not include the file extension in your `extends:` properties - the format in which this ruleset is written should be an implementation detail for ESLint to figure out.

tutorial/README.md

@@ -6,6 +6,7 @@ module.exports = {
   extends: [
     '@strv/javascript/environments/nodejs/v10',
     '@strv/javascript/environments/nodejs/optional',
+    '@strv/javascript/environments/mocha/recommended',
     '@strv/javascript/coding-styles/recommended',
   ],
 
@@ -18,9 +19,6 @@ module.exports = {
     files: [
       'test/**',
     ],
-    env: {
-      mocha: true,
-    },
 
     rules: {
       'func-names': 'off',

tutorial/nodejs-eslintrc.js

@@ -79,6 +79,10 @@ module.exports = {
     // them.
     'no-plusplus': 0,
 
+    // Disallow certain object properties
+    // Unused, no use case.
+    'no-restricted-properties': 0,
+
     // Disallow use of the void operator
     // void is quite useful with IIFEs and for discarding return values when using return for
     // short-circuiting.
@@ -179,5 +183,52 @@ module.exports = {
     // Unused, too restrictive, although I do agree about imorting stuff from parent modules'
     // subdirectories is generally a bad idea... ⚠️
     'import/no-relative-parent-imports': 0,
+
+    // Disallow hooks
+    // Unused, hooks are quite useful if they are used responsibly.
+    'mocha/no-hooks': 0,
+
+    // Disallow hooks for a single test or test suite
+    // Unused, usually you start with the setup hooks and write the first test, and once everything
+    // is working you continue writing new tests.
+    'mocha/no-hooks-for-single-case': 0,
+
+    // Disallow arrow functions as arguments to mocha functions
+    // Unused, arrow functions are preferred unless you need to access `this` inside of them.
+    'mocha/no-mocha-arrows': 0,
+
+    // Disallow pending tests
+    // Unused, Mocha already displays pending tests quite nicely, no need to bother the developer
+    // with extra warnings from the linter.
+    'mocha/no-pending-tests': 0,
+
+    // Disallow duplicate uses of a hook at the same level inside a describe
+    // Unused, too restrictive. Sometimes it is useful to have the preparaction code separated, to
+    // "stand out" to make it more obvious.
+    'mocha/no-sibling-hooks': 0,
+
+    // Disallow skipped tests
+    // Unused, too restrictive. Developers should be able to author and commit pending tests.
+    'mocha/no-skipped-tests': 0,
+
+    // Disallow synchronous tests
+    // Unused, too restrictive.
+    'mocha/no-synchronous-tests': 0,
+
+    // Disallow top-level hooks
+    // Unused, too restrictive.
+    'mocha/no-top-level-hooks': 0,
+
+    // Require using arrow functions for callbacks
+    // Unused, the ESLint's original implementation works just fine for Mocha tests as well.
+    'mocha/prefer-arrow-callback': 0,
+
+    // Match suite descriptions against a pre-configured regular expression
+    // Unused, too restrictive.
+    'mocha/valid-suite-description': 0,
+
+    // Match test descriptions against a pre-configured regular expression
+    // Unused, too restrictive.
+    'mocha/valid-test-description': 0,
   },
 }