assert = require("assert"),
path = require("path"),
util = require("util"),
- lodash = require("lodash"),
+ merge = require("lodash.merge"),
+ equal = require("fast-deep-equal"),
+ Traverser = require("../../lib/shared/traverser"),
{ getRuleOptionsSchema, validate } = require("../shared/config-validator"),
{ Linter, SourceCodeFixer, interpolate } = require("../linter");
const ajv = require("../shared/ajv")({ strictDefaults: true });
+const espreePath = require.resolve("espree");
+const parserSymbol = Symbol.for("eslint.RuleTester.parser");
+
+//------------------------------------------------------------------------------
+// Typedefs
+//------------------------------------------------------------------------------
+
+/** @typedef {import("../shared/types").Parser} Parser */
+
+/**
+ * A test case that is expected to pass lint.
+ * @typedef {Object} ValidTestCase
+ * @property {string} code Code for the test case.
+ * @property {any[]} [options] Options for the test case.
+ * @property {{ [name: string]: any }} [settings] Settings for the test case.
+ * @property {string} [filename] The fake filename for the test case. Useful for rules that make assertion about filenames.
+ * @property {string} [parser] The absolute path for the parser.
+ * @property {{ [name: string]: any }} [parserOptions] Options for the parser.
+ * @property {{ [name: string]: "readonly" | "writable" | "off" }} [globals] The additional global variables.
+ * @property {{ [name: string]: boolean }} [env] Environments for the test case.
+ * @property {boolean} [only] Run only this test case or the subset of test cases with this property.
+ */
+
+/**
+ * A test case that is expected to fail lint.
+ * @typedef {Object} InvalidTestCase
+ * @property {string} code Code for the test case.
+ * @property {number | Array<TestCaseError | string | RegExp>} errors Expected errors.
+ * @property {string | null} [output] The expected code after autofixes are applied. If set to `null`, the test runner will assert that no autofix is suggested.
+ * @property {any[]} [options] Options for the test case.
+ * @property {{ [name: string]: any }} [settings] Settings for the test case.
+ * @property {string} [filename] The fake filename for the test case. Useful for rules that make assertion about filenames.
+ * @property {string} [parser] The absolute path for the parser.
+ * @property {{ [name: string]: any }} [parserOptions] Options for the parser.
+ * @property {{ [name: string]: "readonly" | "writable" | "off" }} [globals] The additional global variables.
+ * @property {{ [name: string]: boolean }} [env] Environments for the test case.
+ * @property {boolean} [only] Run only this test case or the subset of test cases with this property.
+ */
+
+/**
+ * A description of a reported error used in a rule tester test.
+ * @typedef {Object} TestCaseError
+ * @property {string | RegExp} [message] Message.
+ * @property {string} [messageId] Message ID.
+ * @property {string} [type] The type of the reported AST node.
+ * @property {{ [name: string]: string }} [data] The data used to fill the message template.
+ * @property {number} [line] The 1-based line number of the reported start location.
+ * @property {number} [column] The 1-based column number of the reported start location.
+ * @property {number} [endLine] The 1-based line number of the reported end location.
+ * @property {number} [endColumn] The 1-based column number of the reported end location.
+ */
+
//------------------------------------------------------------------------------
// Private Members
//------------------------------------------------------------------------------
"filename",
"options",
"errors",
- "output"
+ "output",
+ "only"
];
+/*
+ * All allowed property names in error objects.
+ */
+const errorObjectParameters = new Set([
+ "message",
+ "messageId",
+ "data",
+ "type",
+ "line",
+ "column",
+ "endLine",
+ "endColumn",
+ "suggestions"
+]);
+const friendlyErrorObjectParameterList = `[${[...errorObjectParameters].map(key => `'${key}'`).join(", ")}]`;
+
+/*
+ * All allowed property names in suggestion objects.
+ */
+const suggestionObjectParameters = new Set([
+ "desc",
+ "messageId",
+ "data",
+ "output"
+]);
+const friendlySuggestionObjectParameterList = `[${[...suggestionObjectParameters].map(key => `'${key}'`).join(", ")}]`;
+
const hasOwnProperty = Function.call.bind(Object.hasOwnProperty);
/**
*/
function sanitize(text) {
return text.replace(
- /[\u0000-\u0009|\u000b-\u001a]/gu, // eslint-disable-line no-control-regex
+ /[\u0000-\u0009\u000b-\u001a]/gu, // eslint-disable-line no-control-regex
c => `\\u${c.codePointAt(0).toString(16).padStart(4, "0")}`
);
}
+/**
+ * Define `start`/`end` properties as throwing error.
+ * @param {string} objName Object name used for error messages.
+ * @param {ASTNode} node The node to define.
+ * @returns {void}
+ */
+function defineStartEndAsError(objName, node) {
+ Object.defineProperties(node, {
+ start: {
+ get() {
+ throw new Error(`Use ${objName}.range[0] instead of ${objName}.start`);
+ },
+ configurable: true,
+ enumerable: false
+ },
+ end: {
+ get() {
+ throw new Error(`Use ${objName}.range[1] instead of ${objName}.end`);
+ },
+ configurable: true,
+ enumerable: false
+ }
+ });
+}
+
+
+/**
+ * Define `start`/`end` properties of all nodes of the given AST as throwing error.
+ * @param {ASTNode} ast The root node to errorize `start`/`end` properties.
+ * @param {Object} [visitorKeys] Visitor keys to be used for traversing the given ast.
+ * @returns {void}
+ */
+function defineStartEndAsErrorInTree(ast, visitorKeys) {
+ Traverser.traverse(ast, { visitorKeys, enter: defineStartEndAsError.bind(null, "node") });
+ ast.tokens.forEach(defineStartEndAsError.bind(null, "token"));
+ ast.comments.forEach(defineStartEndAsError.bind(null, "token"));
+}
+
+/**
+ * Wraps the given parser in order to intercept and modify return values from the `parse` and `parseForESLint` methods, for test purposes.
+ * In particular, to modify ast nodes, tokens and comments to throw on access to their `start` and `end` properties.
+ * @param {Parser} parser Parser object.
+ * @returns {Parser} Wrapped parser object.
+ */
+function wrapParser(parser) {
+
+ if (typeof parser.parseForESLint === "function") {
+ return {
+ [parserSymbol]: parser,
+ parseForESLint(...args) {
+ const ret = parser.parseForESLint(...args);
+
+ defineStartEndAsErrorInTree(ret.ast, ret.visitorKeys);
+ return ret;
+ }
+ };
+ }
+
+ return {
+ [parserSymbol]: parser,
+ parse(...args) {
+ const ast = parser.parse(...args);
+
+ defineStartEndAsErrorInTree(ast);
+ return ast;
+ }
+ };
+}
+
//------------------------------------------------------------------------------
// Public Interface
//------------------------------------------------------------------------------
// default separators for testing
const DESCRIBE = Symbol("describe");
const IT = Symbol("it");
+const IT_ONLY = Symbol("itOnly");
/**
* This is `it` default handler if `it` don't exist.
* configuration and the default configuration.
* @type {Object}
*/
- this.testerConfig = lodash.merge(
-
- // we have to clone because merge uses the first argument for recipient
- lodash.cloneDeep(defaultConfig),
+ this.testerConfig = merge(
+ {},
+ defaultConfig,
testerConfig,
{ rules: { "rule-tester/validate-ast": "error" } }
);
* @returns {void}
*/
static resetDefaultConfig() {
- defaultConfig = lodash.cloneDeep(testerDefaultConfig);
+ defaultConfig = merge({}, testerDefaultConfig);
}
this[IT] = value;
}
+ /**
+ * Adds the `only` property to a test to run it in isolation.
+ * @param {string | ValidTestCase | InvalidTestCase} item A single test to run by itself.
+ * @returns {ValidTestCase | InvalidTestCase} The test with `only` set.
+ */
+ static only(item) {
+ if (typeof item === "string") {
+ return { code: item, only: true };
+ }
+
+ return { ...item, only: true };
+ }
+
+ static get itOnly() {
+ if (typeof this[IT_ONLY] === "function") {
+ return this[IT_ONLY];
+ }
+ if (typeof this[IT] === "function" && typeof this[IT].only === "function") {
+ return Function.bind.call(this[IT].only, this[IT]);
+ }
+ if (typeof it === "function" && typeof it.only === "function") {
+ return Function.bind.call(it.only, it);
+ }
+
+ if (typeof this[DESCRIBE] === "function" || typeof this[IT] === "function") {
+ throw new Error(
+ "Set `RuleTester.itOnly` to use `only` with a custom test framework.\n" +
+ "See https://eslint.org/docs/developer-guide/nodejs-api#customizing-ruletester for more."
+ );
+ }
+ if (typeof it === "function") {
+ throw new Error("The current test framework does not support exclusive tests with `only`.");
+ }
+ throw new Error("To use `only`, use RuleTester with a test framework that provides `it.only()` like Mocha.");
+ }
+
+ static set itOnly(value) {
+ this[IT_ONLY] = value;
+ }
+
/**
* Define a rule for one particular run of tests.
* @param {string} name The name of the rule to define.
* Adds a new rule test to execute.
* @param {string} ruleName The name of the rule to run.
* @param {Function} rule The rule to test.
- * @param {Object} test The collection of tests to run.
+ * @param {{
+ * valid: (ValidTestCase | string)[],
+ * invalid: InvalidTestCase[]
+ * }} test The collection of tests to run.
* @returns {void}
*/
run(ruleName, rule, test) {
scenarioErrors = [],
linter = this.linter;
- if (lodash.isNil(test) || typeof test !== "object") {
+ if (!test || typeof test !== "object") {
throw new TypeError(`Test Scenarios for rule ${ruleName} : Could not find test scenario object`);
}
requiredScenarios.forEach(scenarioType => {
- if (lodash.isNil(test[scenarioType])) {
+ if (!test[scenarioType]) {
scenarioErrors.push(`Could not find any ${scenarioType} test scenarios`);
}
});
* @private
*/
function runRuleForItem(item) {
- let config = lodash.cloneDeep(testerConfig),
+ let config = merge({}, testerConfig),
code, filename, output, beforeAST, afterAST;
if (typeof item === "string") {
* Assumes everything on the item is a config except for the
* parameters used by this tester
*/
- const itemConfig = lodash.omit(item, RuleTesterParameters);
+ const itemConfig = { ...item };
+
+ for (const parameter of RuleTesterParameters) {
+ delete itemConfig[parameter];
+ }
/*
* Create the config object from the tester config and this item
* specific configurations.
*/
- config = lodash.merge(
+ config = merge(
config,
itemConfig
);
if (typeof config.parser === "string") {
assert(path.isAbsolute(config.parser), "Parsers provided as strings to RuleTester must be absolute paths");
- linter.defineParser(config.parser, require(config.parser));
+ } else {
+ config.parser = espreePath;
}
+ linter.defineParser(config.parser, wrapParser(require(config.parser)));
+
if (schema) {
ajv.validateSchema(schema);
// Verify the code.
const messages = linter.verify(code, config, filename);
+ const fatalErrorMessage = messages.find(m => m.fatal);
- // Ignore syntax errors for backward compatibility if `errors` is a number.
- if (typeof item.errors !== "number") {
- const errorMessage = messages.find(m => m.fatal);
-
- assert(!errorMessage, `A fatal parsing error occurred: ${errorMessage && errorMessage.message}`);
- }
+ assert(!fatalErrorMessage, `A fatal parsing error occurred: ${fatalErrorMessage && fatalErrorMessage.message}`);
// Verify if autofix makes a syntax error or not.
if (messages.some(m => m.fix)) {
output = SourceCodeFixer.applyFixes(code, messages).output;
const errorMessageInFix = linter.verify(output, config, filename).find(m => m.fatal);
- assert(!errorMessageInFix, `A fatal parsing error occurred in autofix: ${errorMessageInFix && errorMessageInFix.message}`);
+ assert(!errorMessageInFix, [
+ "A fatal parsing error occurred in autofix.",
+ `Error: ${errorMessageInFix && errorMessageInFix.message}`,
+ "Autofix output:",
+ output
+ ].join("\n"));
} else {
output = code;
}
* @private
*/
function assertASTDidntChange(beforeAST, afterAST) {
- if (!lodash.isEqual(beforeAST, afterAST)) {
+ if (!equal(beforeAST, afterAST)) {
assert.fail("Rule should not modify AST.");
}
}
const messages = result.messages;
assert.strictEqual(messages.length, 0, util.format("Should have no errors but had %d: %s",
- messages.length, util.inspect(messages)));
+ messages.length,
+ util.inspect(messages)));
assertASTDidntChange(result.beforeAST, result.afterAST);
}
assert.ok(item.errors || item.errors === 0,
`Did not specify errors for an invalid test of ${ruleName}`);
+ if (Array.isArray(item.errors) && item.errors.length === 0) {
+ assert.fail("Invalid cases must have at least one error");
+ }
+
+ const ruleHasMetaMessages = hasOwnProperty(rule, "meta") && hasOwnProperty(rule.meta, "messages");
+ const friendlyIDList = ruleHasMetaMessages ? `[${Object.keys(rule.meta.messages).map(key => `'${key}'`).join(", ")}]` : null;
+
const result = runRuleForItem(item);
const messages = result.messages;
-
if (typeof item.errors === "number") {
+
+ if (item.errors === 0) {
+ assert.fail("Invalid cases must have 'error' value greater than 0");
+ }
+
assert.strictEqual(messages.length, item.errors, util.format("Should have %d error%s but had %d: %s",
- item.errors, item.errors === 1 ? "" : "s", messages.length, util.inspect(messages)));
+ item.errors,
+ item.errors === 1 ? "" : "s",
+ messages.length,
+ util.inspect(messages)));
} else {
assert.strictEqual(
- messages.length, item.errors.length,
- util.format(
+ messages.length, item.errors.length, util.format(
"Should have %d error%s but had %d: %s",
- item.errors.length, item.errors.length === 1 ? "" : "s", messages.length, util.inspect(messages)
+ item.errors.length,
+ item.errors.length === 1 ? "" : "s",
+ messages.length,
+ util.inspect(messages)
)
);
// Just an error message.
assertMessageMatches(message.message, error);
- } else if (typeof error === "object") {
+ } else if (typeof error === "object" && error !== null) {
/*
* Error object.
* This may have a message, messageId, data, node type, line, and/or
* column.
*/
+
+ Object.keys(error).forEach(propertyName => {
+ assert.ok(
+ errorObjectParameters.has(propertyName),
+ `Invalid error property name '${propertyName}'. Expected one of ${friendlyErrorObjectParameterList}.`
+ );
+ });
+
if (hasOwnProperty(error, "message")) {
assert.ok(!hasOwnProperty(error, "messageId"), "Error should not specify both 'message' and a 'messageId'.");
assert.ok(!hasOwnProperty(error, "data"), "Error should not specify both 'data' and 'message'.");
assertMessageMatches(message.message, error.message);
} else if (hasOwnProperty(error, "messageId")) {
assert.ok(
- hasOwnProperty(rule, "meta") && hasOwnProperty(rule.meta, "messages"),
+ ruleHasMetaMessages,
"Error can not use 'messageId' if rule under test doesn't define 'meta.messages'."
);
if (!hasOwnProperty(rule.meta.messages, error.messageId)) {
- const friendlyIDList = `[${Object.keys(rule.meta.messages).map(key => `'${key}'`).join(", ")}]`;
-
assert(false, `Invalid messageId '${error.messageId}'. Expected one of ${friendlyIDList}.`);
}
assert.strictEqual(
assert.strictEqual(message.suggestions.length, error.suggestions.length, `Error should have ${error.suggestions.length} suggestions. Instead found ${message.suggestions.length} suggestions`);
error.suggestions.forEach((expectedSuggestion, index) => {
+ assert.ok(
+ typeof expectedSuggestion === "object" && expectedSuggestion !== null,
+ "Test suggestion in 'suggestions' array must be an object."
+ );
+ Object.keys(expectedSuggestion).forEach(propertyName => {
+ assert.ok(
+ suggestionObjectParameters.has(propertyName),
+ `Invalid suggestion property name '${propertyName}'. Expected one of ${friendlySuggestionObjectParameterList}.`
+ );
+ });
+
const actualSuggestion = message.suggestions[index];
+ const suggestionPrefix = `Error Suggestion at index ${index} :`;
+
+ if (hasOwnProperty(expectedSuggestion, "desc")) {
+ assert.ok(
+ !hasOwnProperty(expectedSuggestion, "data"),
+ `${suggestionPrefix} Test should not specify both 'desc' and 'data'.`
+ );
+ assert.strictEqual(
+ actualSuggestion.desc,
+ expectedSuggestion.desc,
+ `${suggestionPrefix} desc should be "${expectedSuggestion.desc}" but got "${actualSuggestion.desc}" instead.`
+ );
+ }
- /**
- * Tests equality of a suggestion key if that key is defined in the expected output.
- * @param {string} key Key to validate from the suggestion object
- * @returns {void}
- */
- function assertSuggestionKeyEquals(key) {
- if (hasOwnProperty(expectedSuggestion, key)) {
- assert.deepStrictEqual(actualSuggestion[key], expectedSuggestion[key], `Error suggestion at index: ${index} should have desc of: "${actualSuggestion[key]}"`);
+ if (hasOwnProperty(expectedSuggestion, "messageId")) {
+ assert.ok(
+ ruleHasMetaMessages,
+ `${suggestionPrefix} Test can not use 'messageId' if rule under test doesn't define 'meta.messages'.`
+ );
+ assert.ok(
+ hasOwnProperty(rule.meta.messages, expectedSuggestion.messageId),
+ `${suggestionPrefix} Test has invalid messageId '${expectedSuggestion.messageId}', the rule under test allows only one of ${friendlyIDList}.`
+ );
+ assert.strictEqual(
+ actualSuggestion.messageId,
+ expectedSuggestion.messageId,
+ `${suggestionPrefix} messageId should be '${expectedSuggestion.messageId}' but got '${actualSuggestion.messageId}' instead.`
+ );
+ if (hasOwnProperty(expectedSuggestion, "data")) {
+ const unformattedMetaMessage = rule.meta.messages[expectedSuggestion.messageId];
+ const rehydratedDesc = interpolate(unformattedMetaMessage, expectedSuggestion.data);
+
+ assert.strictEqual(
+ actualSuggestion.desc,
+ rehydratedDesc,
+ `${suggestionPrefix} Hydrated test desc "${rehydratedDesc}" does not match received desc "${actualSuggestion.desc}".`
+ );
}
+ } else {
+ assert.ok(
+ !hasOwnProperty(expectedSuggestion, "data"),
+ `${suggestionPrefix} Test must specify 'messageId' if 'data' is used.`
+ );
}
- assertSuggestionKeyEquals("desc");
- assertSuggestionKeyEquals("messageId");
if (hasOwnProperty(expectedSuggestion, "output")) {
const codeWithAppliedSuggestion = SourceCodeFixer.applyFixes(item.code, [actualSuggestion]).output;
} else {
assert.strictEqual(result.output, item.output, "Output is incorrect.");
}
+ } else {
+ assert.strictEqual(
+ result.output,
+ item.code,
+ "The rule fixed the code. Please add 'output' property."
+ );
+ }
+
+ // Rules that produce fixes must have `meta.fixable` property.
+ if (result.output !== item.code) {
+ assert.ok(
+ hasOwnProperty(rule, "meta"),
+ "Fixable rules should export a `meta.fixable` property."
+ );
+
+ // Linter throws if a rule that produced a fix has `meta` but doesn't have `meta.fixable`.
}
assertASTDidntChange(result.beforeAST, result.afterAST);
RuleTester.describe(ruleName, () => {
RuleTester.describe("valid", () => {
test.valid.forEach(valid => {
- RuleTester.it(sanitize(typeof valid === "object" ? valid.code : valid), () => {
- testValidTemplate(valid);
- });
+ RuleTester[valid.only ? "itOnly" : "it"](
+ sanitize(typeof valid === "object" ? valid.code : valid),
+ () => {
+ testValidTemplate(valid);
+ }
+ );
});
});
RuleTester.describe("invalid", () => {
test.invalid.forEach(invalid => {
- RuleTester.it(sanitize(invalid.code), () => {
- testInvalidTemplate(invalid);
- });
+ RuleTester[invalid.only ? "itOnly" : "it"](
+ sanitize(invalid.code),
+ () => {
+ testInvalidTemplate(invalid);
+ }
+ );
});
});
});
}
}
-RuleTester[DESCRIBE] = RuleTester[IT] = null;
+RuleTester[DESCRIBE] = RuleTester[IT] = RuleTester[IT_ONLY] = null;
module.exports = RuleTester;
projects / dotfiles / .git / blobdiff