New: test-case-shorthand-strings rule

Author: not-an-aardvark

Diff for: .eslintrc.js

@@ -24,5 +24,6 @@ module.exports = {
   rules: {
     'require-jsdoc': 'error',
     'eslint-plugin/report-message-format': ['error', '^[^a-z].*\\.$'],
+    'eslint-plugin/test-case-shorthand-strings': 'off',
   },
 };

Diff for: README.md

@@ -62,3 +62,4 @@ Name | ✔️ | 🛠 | Description
 [report-message-format](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/report-message-format.md) | ✔️ | | Enforces a consistent format for report messages
 [require-meta-fixable](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/require-meta-fixable.md) | ✔️ | | Requires a `meta.fixable` property for fixable rules
 [no-missing-placeholders](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/no-missing-placeholders.md) | ✔️ | | Disallows missing placeholders in rule report messages
+[test-case-shorthand-strings](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/test-case-shorthand-strings.md) | | | Enforces consistent usage of shorthand strings for test cases with no options

Diff for: docs/rules/test-case-shorthand-strings.md

@@ -0,0 +1,257 @@
+# Enforce consistent usage of shorthand strings for test cases with no options (test-case-shorthand-strings)
+
+When writing valid test cases for rules with `RuleTester`, one can optionally include a string as a test case instead of an object, if the the test case does not use any options.
+
+```js
+ruleTester.run('example-rule', rule, {
+  valid: [
+
+    // shorthand string
+    'validTestCase;',
+
+    // longform object
+    {
+      code: 'anotherValidTestCase;'
+    }
+  ],
+  invalid: [
+    // ...
+  ]
+});
+```
+
+Some developers prefer using this shorthand because it's more concise, but others prefer not to use the shorthand for consistency, so that all test cases are provided as objects. Regardless of your preference, it's generally better to be consistent throughout a project.
+
+## Rule Details
+
+This rule aims to enforce or disallow the use of strings as test cases.
+
+### Options
+
+This rule has a string option:
+
+* `as-needed` (default): Requires the use of shorthand strings wherever possible.
+* `never`: Disallows the use of shorthand strings.
+* `consistent`: Requires that either all valid test cases use shorthand strings, or that no valid test cases use them.
+* `consistent-as-needed`: Requires that all valid test cases use the longer object form if there are any valid test cases that require the object form. Otherwise, requires all valid test cases to use shorthand strings.
+
+#### `as-needed`
+
+Examples of **incorrect** code for this rule with the default `as-needed` option:
+
+```js
+/* eslint eslint-plugin/test-case-shorthand-strings: "error" */
+
+ruleTester.run('example-rule', rule, {
+  valid: [
+    {
+      code: 'validTestCase;'
+    },
+    {
+      code: 'anotherValidTestCase;'
+    }
+  ],
+  invalid: []
+});
+```
+
+Examples of **correct** code for this rule with the default `as-needed` option:
+
+```js
+/* eslint eslint-plugin/test-case-shorthand-strings: "error" */
+
+ruleTester.run('example-rule', rule, {
+  valid: [
+    'validTestCase;',
+    'anotherValidTestCase;',
+    {
+      code: 'testCaseWithOption;',
+      options: ["foo"]
+    }
+  ],
+  invalid: []
+});
+```
+
+#### `never`
+
+Examples of **incorrect** code for this rule with the `never` option:
+
+```js
+/* eslint eslint-plugin/test-case-shorthand-strings: ["error", "never"] */
+
+ruleTester.run('example-rule', rule, {
+  valid: [
+    'validTestCase;',
+    'anotherValidTestCase;'
+  ],
+  invalid: []
+});
+```
+
+Examples of **correct** code for this rule with the `never` option:
+
+```js
+/* eslint eslint-plugin/test-case-shorthand-strings: ["error", "never"] */
+
+ruleTester.run('example-rule', rule, {
+  valid: [
+    {
+      code: 'validTestCase;'
+    },
+    {
+      code: 'anotherValidTestCase;'
+    }
+  ],
+  invalid: []
+});
+```
+
+#### `consistent`
+
+Examples of **incorrect** code for this rule with the `consistent` option:
+
+```js
+/* eslint eslint-plugin/test-case-shorthand-strings: ["error", "consistent"] */
+
+ruleTester.run('example-rule', rule, {
+  valid: [
+    'validTestCase;',
+    'anotherValidTestCase;',
+    {
+      code: 'testCaseWithOption',
+      options: ["foo"]
+    }
+  ],
+  invalid: []
+});
+```
+
+Examples of **correct** code for this rule with the `consistent` option:
+
+```js
+/* eslint eslint-plugin/test-case-shorthand-strings: ["error", "consistent"] */
+
+ruleTester.run('example-rule', rule, {
+  valid: [
+    {
+      code: 'validTestCase;'
+    },
+    {
+      code: 'anotherValidTestCase'
+    }
+    {
+      code: 'testCaseWithOption',
+      options: ["foo"]
+    }
+  ],
+  invalid: []
+});
+
+ruleTester.run('example-rule', rule, {
+  valid: [
+    'validTestCase;'
+    'anotherValidTestCase'
+  ],
+  invalid: []
+});
+
+ruleTester.run('example-rule', rule, {
+  valid: [
+    {
+      code: 'validTestCase;'
+    },
+    {
+      code: 'anotherValidTestCase'
+    }
+  ],
+  invalid: []
+});
+```
+
+#### `never`
+
+Examples of **incorrect** code for this rule with the `consistent-as-needed` option:
+
+```js
+/* eslint eslint-plugin/test-case-shorthand-strings: ["error", "consistent-as-needed"] */
+
+ruleTester.run('example-rule', rule, {
+  valid: [
+    'validTestCase;',
+    {
+      code: 'anotherValidTestCase'
+    }
+  ],
+  invalid: []
+});
+
+ruleTester.run('example-rule', rule, {
+  valid: [
+    'validTestCase;',
+    'anotherValidTestCase;',
+    {
+      code: 'testCaseWithOption;',
+      options: ['foo']
+    }
+  ],
+  invalid: []
+});
+
+ruleTester.run('example-rule', rule, {
+  valid: [
+    {
+      code: 'validTestCase;'
+    },
+    {
+      code: 'anotherValidTestCase;'
+    }
+  ],
+  invalid: []
+});
+```
+
+Examples of **correct** code for this rule with the `consistent-as-needed` option:
+
+```js
+/* eslint eslint-plugin/test-case-shorthand-strings: ["error", "consistent-as-needed"] */
+
+ruleTester.run('example-rule', rule, {
+  valid: [
+    'validTestCase;'
+    'anotherValidTestCase;'
+  ],
+  invalid: []
+});
+
+ruleTester.run('example-rule', rule, {
+  valid: [
+    {
+      code: 'validTestCase;'
+    },
+    {
+      code: 'anotherValidTestCase;'
+    },
+    {
+      code: 'testCaseWithOption;',
+      options: ['foo']
+    }
+  ],
+  invalid: []
+});
+```
+
+## Known Limitations
+
+* Test cases which are neither object literals nor string literals are ignored by this rule.
+* In order to find your test cases, your test file needs to match the following common pattern:
+  * `new RuleTester()` or `new (require('eslint')).RuleTester()` is called at the top level of the file
+  * `ruleTester.run` is called at the top level with the same variable (or in the same expression) as the `new RuleTester` instantiation
+
+## When Not To Use It
+
+If you don't care about consistent usage of shorthand strings, you should not turn on this rule.
+
+## Further Reading
+
+* [`RuleTester` documentation](http://eslint.org/docs/developer-guide/working-with-plugins#testing)

Diff for: lib/rules/test-case-shorthand-strings.js

@@ -0,0 +1,80 @@
+/**
+ * @fileoverview Enforce consistent usage of shorthand strings for test cases with no options
+ * @author Teddy Katz
+ */
+
+'use strict';
+
+const utils = require('../utils');
+
+// ------------------------------------------------------------------------------
+// Rule Definition
+// ------------------------------------------------------------------------------
+
+module.exports = {
+  meta: {
+    docs: {
+      description: 'Enforce consistent usage of shorthand strings for test cases with no options',
+      category: 'Tests',
+      recommended: false,
+    },
+    schema: [{ enum: ['as-needed', 'never', 'consistent', 'consistent-as-needed'] }],
+  },
+
+  create (context) {
+    const shorthandOption = context.options[0] || 'as-needed';
+    // ----------------------------------------------------------------------
+    // Helpers
+    // ----------------------------------------------------------------------
+
+    /**
+    * Reports test cases as necessary
+    * @param {object[]} cases A list of test case nodes
+    * @returns {void}
+    */
+    function reportTestCases (cases) {
+      const caseInfoList = cases.map(testCase => {
+        if (testCase.type === 'Literal' || testCase.type === 'TemplateLiteral') {
+          return { node: testCase, shorthand: true, needsLongform: false };
+        }
+        if (testCase.type === 'ObjectExpression') {
+          return {
+            node: testCase,
+            shorthand: false,
+            needsLongform: !(testCase.properties.length === 1 && utils.getKeyName(testCase.properties[0]) === 'code'),
+          };
+        }
+        return null;
+      }).filter(Boolean);
+
+      const isConsistent = new Set(caseInfoList.map(caseInfo => caseInfo.shorthand)).size <= 1;
+      const hasCaseNeedingLongform = caseInfoList.some(caseInfo => caseInfo.needsLongform);
+
+      caseInfoList.filter({
+        'as-needed': caseInfo => !caseInfo.shorthand && !caseInfo.needsLongform,
+        never: caseInfo => caseInfo.shorthand,
+        consistent: isConsistent ? () => false : caseInfo => caseInfo.shorthand,
+        'consistent-as-needed': caseInfo => caseInfo.shorthand === hasCaseNeedingLongform,
+      }[shorthandOption]).forEach(badCaseInfo => {
+        context.report({
+          node: badCaseInfo.node,
+          message: 'Use {{preferred}} for this test case instead of {{actual}}.',
+          data: {
+            preferred: badCaseInfo.shorthand ? 'an object' : 'a string',
+            actual: badCaseInfo.shorthand ? 'a string' : 'an object',
+          },
+        });
+      });
+    }
+
+    // ----------------------------------------------------------------------
+    // Public
+    // ----------------------------------------------------------------------
+
+    return {
+      Program (ast) {
+        utils.getTestInfo(context, ast).map(testRun => testRun.valid).filter(Boolean).forEach(reportTestCases);
+      },
+    };
+  },
+};