Node.js API 参考
虽然 ESLint 旨在在命令行上运行，但可以通过 Node.js API 以编程方式使用 ESLint。Node.js API 的目的是允许插件和工具作者直接使用 ESLint 功能，而无需通过命令行界面。
注意：自行承担使用未记录 API 部分的风险。仅本文档中明确提及的部分才获准使用，并将保持稳定和可靠。任何未记录的部分都是不稳定的，可能会在任何时候更改或删除。
ESLint 类
ESLint 类是 Node.js 应用程序中使用的主要类。
此类依赖于 Node.js 的 fs 模块和文件系统，因此您不能在浏览器中使用它。如果要检查浏览器中的代码，请改用 Linter 类。
以下是如何使用 ESLint 类的简单示例
const { ESLint } = require("eslint");
(async function main() {
// 1. Create an instance.
const eslint = new ESLint();
// 2. Lint files.
const results = await eslint.lintFiles(["lib/**/*.js"]);
// 3. Format the results.
const formatter = await eslint.loadFormatter("stylish");
const resultText = formatter.format(results);
// 4. Output it.
console.log(resultText);
})().catch((error) => {
process.exitCode = 1;
console.error(error);
});
这是一个自动修复 lint 问题的示例
const { ESLint } = require("eslint");
(async function main() {
// 1. Create an instance with the `fix` option.
const eslint = new ESLint({ fix: true });
// 2. Lint files. This doesn't modify target files.
const results = await eslint.lintFiles(["lib/**/*.js"]);
// 3. Modify the files with the fixed code.
await ESLint.outputFixes(results);
// 4. Format the results.
const formatter = await eslint.loadFormatter("stylish");
const resultText = formatter.format(results);
// 5. Output it.
console.log(resultText);
})().catch((error) => {
process.exitCode = 1;
console.error(error);
});
以下是如何使用 ESLint 类和 lintText API 的示例
const { ESLint } = require("eslint");
const testCode = `
const name = "eslint";
if(true) {
console.log("constant condition warning")
};
`;
(async function main() {
// 1. Create an instance
const eslint = new ESLint({
overrideConfigFile: true,
overrideConfig: {
languageOptions: {
ecmaVersion: 2018,
sourceType: "commonjs"
}
},
});
// 2. Lint text.
const results = await eslint.lintText(testCode);
// 3. Format the results.
const formatter = await eslint.loadFormatter("stylish");
const resultText = formatter.format(results);
// 4. Output it.
console.log(resultText);
})().catch((error) => {
process.exitCode = 1;
console.error(error);
});
◆ new ESLint(options)
const eslint = new ESLint(options);
创建一个新的 ESLint 实例。
参数
ESLint 构造函数接受一个 options 对象。如果您省略 options 对象，则它将对所有选项使用默认值。options 对象具有以下属性。
文件枚举
options.cwd(string)
默认为process.cwd()。工作目录。这必须是绝对路径。options.errorOnUnmatchedPattern(boolean)
默认为true。除非设置为false，否则eslint.lintFiles()方法在找不到目标文件时将抛出错误。options.globInputPaths(boolean)
默认为true。如果存在false，则eslint.lintFiles()方法不解释 glob 模式。options.ignore(boolean)
默认为true。如果存在false，则eslint.lintFiles()方法不尊重配置中的ignorePatterns。options.ignorePatterns(string[] | null)
默认为null。除了配置忽略之外，还要使用的忽略文件模式。这些模式相对于cwd。options.passOnNoPatterns(boolean)
默认为false。当设置为true时，缺少模式会导致 lint 操作短路并且不报告任何错误。options.warnIgnored(boolean)
默认为true。当文件列表包含被忽略的文件时显示警告。
代码检查
options.allowInlineConfig(boolean)
默认为true。如果存在false，则 ESLint 会抑制源代码中的指令注释。如果此选项为false，则会覆盖配置中的noInlineConfig设置。options.baseConfig(ConfigData | ConfigData[] | null)
默认为null。配置对象，由与此实例一起使用的所有配置扩展。您可以使用此选项定义如果您的配置文件未配置它将使用的默认设置。options.overrideConfig(ConfigData | ConfigData[] | null)
默认为null。配置对象，覆盖与此实例一起使用的所有配置。您可以使用此选项定义即使您的配置文件配置了它也将使用的设置。options.overrideConfigFile(string | boolean)
默认为false。配置文件的路径，覆盖与此实例一起使用的所有配置。options.overrideConfig选项在此选项应用后应用。options.plugins(Record<string, Plugin> | null)
默认为null。ESLint 用于配置的plugins设置的插件实现。这是一个类似于映射的对象。这些键是插件 ID，每个值都是实现。options.ruleFilter(({ruleId: string, severity: number}) => boolean)
默认为() => true。一个谓词函数，用于过滤要运行的规则。此函数使用包含ruleId和severity的对象调用，如果应运行该规则，则返回true。options.stats(boolean)
默认为false。当设置为true时，会将其他统计信息添加到 lint 结果中（请参阅 Stats 类型）。
自动修复
options.fix(boolean | (message: LintMessage) => boolean)
默认为false。如果存在true，则eslint.lintFiles()和eslint.lintText()方法以自动修复模式工作。如果存在谓词函数，则方法将每个 lint 消息传递给该函数，然后仅使用该函数返回true的 lint 消息。options.fixTypes(("directive" | "problem" | "suggestion" | "layout")[] | null)
默认为null。eslint.lintFiles()和eslint.lintText()方法用于自动修复的规则类型。
与缓存相关
options.cache(boolean)
默认为false。如果存在true，则eslint.lintFiles()方法缓存 lint 结果，如果每个目标文件未更改则使用它。请注意，当您升级 ESLint 插件时，ESLint 不会清除缓存。在这种情况下，您必须手动删除缓存文件。eslint.lintText()方法即使您将options.filePath传递给该方法也不会使用缓存。options.cacheLocation(string)
默认为.eslintcache。eslint.lintFiles()方法将缓存写入此文件。options.cacheStrategy(string)
默认为"metadata"。缓存用于检测更改文件的策略。可以是"metadata"或"content"。
其他选项
options.flags(string[])
默认为[]。要为此实例启用的特性标志。
◆ eslint.lintFiles(patterns)
const results = await eslint.lintFiles(patterns);
此方法检查与 glob 模式匹配的文件，然后返回结果。
参数
patterns(string | string[])
lint 目标文件。这可以包含任何文件路径、目录路径和 glob 模式。
返回值
- (
Promise<LintResult[]>)
将使用 LintResult 对象数组完成的承诺。
◆ eslint.lintText(code, options)
const results = await eslint.lintText(code, options);
此方法检查给定的源代码文本，然后返回结果。
默认情况下，此方法使用适用于当前工作目录（cwd 构造函数选项）中文件的配置。如果要使用其他配置，请传递 options.filePath，ESLint 将加载与 eslint.lintFiles() 对 options.filePath 中的文件使用的配置相同的配置。
如果 options.filePath 的值被配置为忽略，则此方法返回一个空数组。如果 options.warnIgnored 选项与 options.filePath 选项一起设置，则此方法返回一个 LintResult 对象。在这种情况下，结果可能包含一个警告，指示文件被忽略。
参数
第二个参数 options 可选。
code(string)
要检查的源代码文本。options.filePath(string)
可选。源代码文本的文件路径。如果省略，则result.filePath将变为字符串"<text>"。options.warnIgnored(boolean)
可选，默认为传递给构造函数的options.warnIgnored。如果存在true并且options.filePath是 ESLint 应该忽略的文件，则此方法返回一个包含警告消息的 lint 结果。
返回值
- (
Promise<LintResult[]>)
将以 LintResult 对象数组的形式完成的 Promise。为了使此方法与eslint.lintFiles()方法之间的接口相似，即使只有一个 lint 结果，它也是一个数组。
◆ eslint.getRulesMetaForResults(results)
const results = await eslint.lintFiles(patterns);
const rulesMeta = eslint.getRulesMetaForResults(results);
此方法返回一个对象，其中包含在给定 results 中触发 lint 错误的每个规则的元信息。
参数
results(LintResult[])
通过调用ESLint#lintFiles()或ESLint#lintText()返回的 LintResult 对象数组。
返回值
- (
Object)
一个对象的属性名称是来自results的规则 ID，其属性值是规则的元信息（如果可用）。
◆ eslint.calculateConfigForFile(filePath)
const config = await eslint.calculateConfigForFile(filePath);
此方法计算给定文件的配置，这对于调试目的非常有用。
参数
filePath(string)
要计算其配置的文件的路径。目录路径是被禁止的，因为 ESLint 无法处理overrides设置。
返回值
- (
Promise<Object>)
将以配置对象形式完成的 Promise。
◆ eslint.isPathIgnored(filePath)
const isPathIgnored = await eslint.isPathIgnored(filePath);
此方法检查给定文件是否被您的配置忽略。
参数
filePath(string)
要检查的文件的路径。
返回值
- (
Promise<boolean>)
将以文件是否被忽略的形式完成的 Promise。如果文件被忽略，则返回true。
◆ eslint.loadFormatter(nameOrPath)
const formatter = await eslint.loadFormatter(nameOrPath);
此方法加载格式化程序。格式化程序将 lint 结果转换为人类或机器可读的字符串。
参数
nameOrPath(string | undefined)
要检查的文件的路径。允许以下值
返回值
- (
Promise<LoadedFormatter>)
将以 LoadedFormatter 对象形式完成的 Promise。
◆ eslint.hasFlag(flagName)
此方法用于确定是否设置了给定的特性标志，例如以下示例
if (eslint.hasFlag("x_feature")) {
// handle flag
}
参数
flagName(string)
要检查的标志。
返回值
- (
boolean)
如果标志已启用，则为真。
◆ ESLint.version
const version = ESLint.version;
ESLint 的版本字符串。例如 "7.0.0"。
这是一个静态属性。
◆ ESLint.defaultConfig
const defaultConfig = ESLint.defaultConfig;
ESLint 在内部使用的默认配置。这提供给想要使用与 ESLint 相同的默认值计算配置的工具。请记住，默认配置可能会在不同版本之间发生变化，因此您不应该依赖任何特定的键或值存在。
这是一个静态属性。
◆ ESLint.outputFixes(results)
await ESLint.outputFixes(results);
此方法将 ESLint 的自动修复功能修改后的代码写入其相应的文件。如果任何修改后的文件不存在，则此方法不执行任何操作。
这是一个静态方法。
参数
results(LintResult[])
要写入的 LintResult 对象。
返回值
- (
Promise<void>)
所有文件写入后将完成的 Promise。
◆ ESLint.getErrorResults(results)
const filteredResults = ESLint.getErrorResults(results);
此方法复制给定的结果并删除警告。返回值仅包含错误。
这是一个静态方法。
参数
results(LintResult[])
要过滤的 LintResult 对象。
返回值
- (
LintResult[])
已过滤的 LintResult 对象。
◆ LintResult 类型
LintResult 值是每个文件的 lint 结果信息。 eslint.lintFiles() 和 eslint.lintText() 方法返回它。它具有以下属性
filePath(string)
此结果文件的绝对路径。如果文件路径未知（当您没有将options.filePath选项传递给eslint.lintText()方法时），则为字符串"<text>"。messages(LintMessage[])
LintMessage 对象数组。suppressedMessages(SuppressedLintMessage[])
SuppressedLintMessage 对象数组。fixableErrorCount(number)
可以通过fix构造函数选项自动修复的错误数量。fixableWarningCount(number)
可以通过fix构造函数选项自动修复的警告数量。errorCount(number)
错误数量。这包括可修复错误和致命错误。fatalErrorCount(number)
致命错误的数量。warningCount(number)
警告数量。这包括可修复警告。output(string | undefined)
修改后的源代码文本。如果不存在任何可修复的消息，则此属性未定义。source(string | undefined)
原始源代码文本。如果不存在任何消息或存在output属性，则此属性未定义。stats(Stats | undefined)
Stats 对象。它包含使用stats选项收集的 lint 性能统计信息。usedDeprecatedRules({ ruleId: string; replacedBy: string[] }[])
有关用于检查此文件的不推荐使用的规则的信息。
◆ LintMessage 类型
LintMessage 值是每个 lint 错误的信息。 LintResult 类型的 messages 属性包含它。它具有以下属性
ruleId(string|null)
生成此 lint 消息的规则名称。如果此消息是由 ESLint 核心而不是规则生成的，则为null。severity(1 | 2)
此消息的严重性。1表示警告，2表示错误。fatal(boolean | undefined)
如果这是与规则无关的致命错误（例如解析错误），则为true。message(string)
错误消息。line(number | undefined)
此消息起始点的基于 1 的行号。column(number | undefined)
此消息起始点的基于 1 的列号。endLine(number | undefined)
此消息结束点的基于 1 的行号。如果此消息不是范围，则此属性未定义。endColumn(number | undefined)
此消息结束点的基于 1 的列号。如果此消息不是范围，则此属性未定义。fix(EditInfo | undefined)
自动修复的 EditInfo 对象。如果此消息不可修复，则此属性未定义。suggestions({ desc: string; fix: EditInfo }[] | undefined)
建议列表。每个建议都是描述和 EditInfo 对象的组合，用于修复代码。编辑器集成等 API 用户可以选择其中一个来解决此消息的问题。如果此消息没有任何建议，则此属性未定义。
◆ SuppressedLintMessage 类型
SuppressedLintMessage 值是每个被抑制的 lint 错误的信息。 LintResult 类型的 suppressedMessages 属性包含它。它具有以下属性
ruleId(string|null)
与 LintMessage 类型中的ruleId相同。severity(1 | 2)
与 LintMessage 类型中的severity相同。fatal(boolean | undefined)
与 LintMessage 类型中的fatal相同。message(string)
与 LintMessage 类型中的message相同。line(number | undefined)
与 LintMessage 类型中的line相同。column(number | undefined)
与 LintMessage 类型中的column相同。endLine(number | undefined)
与 LintMessage 类型中的endLine相同。endColumn(number | undefined)
与 LintMessage 类型中的endColumn相同。fix(EditInfo | undefined)
与 LintMessage 类型中的fix相同。suggestions({ desc: string; fix: EditInfo }[] | undefined)
与 LintMessage 类型中的suggestions相同。suppressions({ kind: string; justification: string}[])
抑制列表。每个抑制都是类型和理由的组合。
◆ EditInfo 类型
EditInfo 值是编辑文本的信息。 LintMessage 类型的 fix 和 suggestions 属性包含它。它具有以下属性
range([number, number])
要删除的源代码文本中基于 0 的索引对。text(string)
要添加的文本。
此编辑信息表示用 text 属性值替换 range 属性的范围。它类似于 sourceCodeText.slice(0, edit.range[0]) + edit.text + sourceCodeText.slice(edit.range[1])。因此，如果 range[0] 和 range[1] 属性值相同，则为添加，如果 text 属性值为空字符串，则为删除。
◆ LoadedFormatter 类型
LoadedFormatter 值是将 LintResult 对象转换为文本的对象。 eslint.loadFormatter() 方法返回它。它具有以下方法
format((results: LintResult[], resultsMeta?: ResultsMeta) => string | Promise<string>)
将 LintResult 对象转换为文本的方法。resultsMeta是一个可选参数，主要用于 ESLint CLI，并且只能包含maxWarningsExceeded属性，该属性将在此方法调用底层格式化程序函数时通过context对象传递。请注意，ESLint 自动生成context对象的cwd和rulesMeta属性，因此在调用此方法时，您通常不需要传入第二个参数。
loadESLint()
loadESLint() 函数用于希望同时支持当前配置系统（扁平化配置）和旧配置系统（eslintrc）的集成。此函数根据提供的参数返回正确的 ESLint 类实现。
const { loadESLint } = require("eslint");
// loads the default ESLint that the CLI would use based on process.cwd()
const DefaultESLint = await loadESLint();
// loads the flat config version specifically
const FlatESLint = await loadESLint({ useFlatConfig: true });
// loads the legacy version specifically
const LegacyESLint = await loadESLint({ useFlatConfig: false });
然后，您可以使用返回的构造函数实例化一个新的 ESLint 实例，如下所示
// loads the default ESLint that the CLI would use based on process.cwd()
const DefaultESLint = await loadESLint();
const eslint = new DefaultESLint();
如果您不确定返回的构造函数使用的是哪个配置系统，请检查 configType 属性，该属性为 "flat" 或 "eslintrc"。
// loads the default ESLint that the CLI would use based on process.cwd()
const DefaultESLint = await loadESLint();
if (DefaultESLint.configType === "flat") {
// do something specific to flat config
}
如果您不需要同时支持旧的和新的配置系统，建议直接使用 ESLint 构造函数。
SourceCode
SourceCode 类型表示 ESLint 执行的已解析源代码。它在 ESLint 内部使用，并且也可以用于使用已解析的代码。您可以通过传入表示代码的文本字符串和 ESTree 格式的抽象语法树 (AST)（包括位置信息、范围信息、注释和标记）来创建一个新的 SourceCode 实例。
const SourceCode = require("eslint").SourceCode;
const code = new SourceCode("var foo = bar;", ast);
如果 AST 缺少任何必需的信息，则 SourceCode 构造函数会抛出错误。
SourceCode 构造函数会去除 Unicode BOM。请注意，AST 也应该从去除 BOM 的文本中解析。
const SourceCode = require("eslint").SourceCode;
const code = new SourceCode("\uFEFFvar foo = bar;", ast);
assert(code.hasBOM === true);
assert(code.text === "var foo = bar;");
SourceCode#splitLines()
这是 SourceCode 上的一个静态函数，用于将源代码文本拆分为一个行数组。
const SourceCode = require("eslint").SourceCode;
const code = "var a = 1;\nvar b = 2;"
// split code into an array
const codeLines = SourceCode.splitLines(code);
/*
Value of codeLines will be
[
"var a = 1;",
"var b = 2;"
]
*/
Linter
Linter 对象执行 JavaScript 代码的实际评估。它不执行任何文件系统操作，它只是解析和报告代码。特别是，Linter 对象不处理配置文件。除非您在浏览器中工作，否则您可能希望改为使用 ESLint 类。
Linter 是一个构造函数，您可以通过传入要使用的选项来创建一个新实例。可用的选项如下：
cwd- 应被视为当前工作目录的目录的路径。规则可以通过context.cwd或调用context.getCwd()来访问它（参见 上下文对象）。如果cwd为undefined，则如果定义了全局process对象（例如，在 Node.js 运行时中），它将被规范化为process.cwd()，否则为undefined。
例如
const Linter = require("eslint").Linter;
const linter1 = new Linter({ cwd: 'path/to/project' });
const linter2 = new Linter();
在此示例中，在 linter1 上运行的规则将从 context.cwd 或调用 context.getCwd() 时获取 path/to/project。在 linter2 上运行的规则将获取 process.cwd()（如果定义了全局 process 对象）或 undefined（例如在浏览器 https://eslint.org.cn/demo 上）。
Linter#verify
Linter 上最重要的方法是 verify()，它会启动给定文本的代码检查。此方法接受三个参数
code- 要检查的源代码（字符串或SourceCode实例）。config- 配置对象 或配置对象数组。- 注意：如果您想要检查文本并从文件系统读取配置，请改用
ESLint#lintFiles()或ESLint#lintText()。
- 注意：如果您想要检查文本并从文件系统读取配置，请改用
options- （可选）此运行的其他选项。filename- （可选）与源代码关联的文件名。preprocess- （可选）插件中的处理器 文档将其描述为preprocess方法的函数。postprocess- （可选）插件中的处理器 文档将其描述为postprocess方法的函数。filterCodeBlock- （可选）一个函数，用于决定代码检查器应该采用哪些代码块。该函数接收两个参数。第一个参数是代码块的虚拟文件名。第二个参数是代码块的文本。如果函数返回true，则代码检查器采用代码块。如果省略了该函数，则代码检查器仅采用*.js代码块。如果您提供了一个filterCodeBlock函数，它会覆盖此默认行为，因此代码检查器不会自动采用*.js代码块。disableFixes- （可选）设置为true时，代码检查器不会生成代码检查结果的fix或suggestions属性。allowInlineConfig- （可选）设置为false以禁用内联注释更改 ESLint 规则。reportUnusedDisableDirectives- （可选）设置为true时，如果在禁用的区域中无论如何都不会报告问题，则为未使用的eslint-disable和eslint-enable指令添加报告的错误。ruleFilter- （可选）一个函数谓词，用于决定哪些规则应该运行。它接收一个包含ruleId和severity的对象，如果应运行该规则，则返回true。
如果第三个参数是字符串，则将其解释为 filename。
您可以像这样调用 verify()
const Linter = require("eslint").Linter;
const linter = new Linter();
const messages = linter.verify("var foo;", {
rules: {
semi: 2
}
}, { filename: "foo.js" });
// or using SourceCode
const Linter = require("eslint").Linter,
linter = new Linter(),
SourceCode = require("eslint").SourceCode;
const code = new SourceCode("var foo = bar;", ast);
const messages = linter.verify(code, {
rules: {
semi: 2
}
}, { filename: "foo.js" });
verify() 方法返回一个包含有关代码检查警告和错误的信息的对象数组。这是一个示例
[
{
fatal: false,
ruleId: "semi",
severity: 2,
line: 1,
column: 23,
message: "Expected a semicolon.",
fix: {
range: [1, 15],
text: ";"
}
}
]
每个代码检查消息可用的信息如下：
column- 发生错误的列。fatal- 通常省略，但如果存在解析错误（与规则无关），则将其设置为 true。line- 发生错误的行。message- 应输出的消息。nodeType- （已弃用：此属性将在 ESLint 的未来版本中删除。）报告问题的节点或标记类型。ruleId- 触发消息的规则的 ID（如果fatal为 true，则为 null）。severity- 根据您的配置，为 1 或 2。endColumn- 发生错误的范围的结束列（如果这不是范围，则省略此属性）。endLine- 发生错误的范围的结束行（如果这不是范围，则省略此属性）。fix- 描述问题修复的对象（如果无可用修复，则省略此属性）。suggestions- 描述编辑器可通过编程方式启用的可能的代码检查修复的对象数组（有关详细信息，请参阅 规则工作文档）。
您可以通过 getSuppressedMessages() 方法获取上次运行中被抑制的消息。如果没有上次运行，getSuppressedMessage() 将返回一个空列表。
const Linter = require("eslint").Linter;
const linter = new Linter();
const messages = linter.verify("var foo = bar; // eslint-disable-line -- Need to suppress", {
rules: {
semi: ["error", "never"]
}
}, { filename: "foo.js" });
const suppressedMessages = linter.getSuppressedMessages();
console.log(suppressedMessages[0].suppressions); // [{ "kind": "directive", "justification": "Need to suppress" }]
您还可以通过使用 getSourceCode() 方法获取 linter 内部使用的 SourceCode 对象的实例。
const Linter = require("eslint").Linter;
const linter = new Linter();
const messages = linter.verify("var foo = bar;", {
rules: {
semi: 2
}
}, { filename: "foo.js" });
const code = linter.getSourceCode();
console.log(code.text); // "var foo = bar;"
通过这种方式，您可以检索上次运行 linter.verify() 时使用的文本和 AST。
Linter#verifyAndFix()
此方法类似于 verify，但它还会运行自动修复逻辑，类似于命令行上的 --fix 标志。结果对象将包含自动修复的代码，以及未自动修复的代码的任何剩余代码检查消息。
const Linter = require("eslint").Linter;
const linter = new Linter();
const messages = linter.verifyAndFix("var foo", {
rules: {
semi: 2
}
});
此方法的输出对象
{
fixed: true,
output: "var foo;",
messages: []
}
可用的信息如下：
fixed- 如果代码已修复，则为 True。output- 修复后的代码文本（如果未应用任何修复，则可能与输入相同）。messages- 给定代码的所有消息的集合（它与上面verify块中解释的信息相同）。
Linter#version/Linter.version
每个 Linter 实例都有一个 version 属性，其中包含 Linter 实例所属的 ESLint 的语义版本号。
const Linter = require("eslint").Linter;
const linter = new Linter();
linter.version; // => '9.0.0'
还有一个 Linter.version 属性，您可以在不实例化 Linter 的情况下读取它。
const Linter = require("eslint").Linter;
Linter.version; // => '9.0.0'
Linter#getTimes()
此方法用于获取在（解析、修复、代码检查）文件上花费的时间。请参阅 统计信息 对象的 times 属性。
Linter#getFixPassCount()
此方法用于获取进行的自动修复传递次数。请参阅 统计信息 对象的 fixPasses 属性。
Linter#hasFlag()
此方法用于确定是否设置了给定的特性标志，例如以下示例
const Linter = require("eslint").Linter;
const linter = new Linter({ flags: ["x_feature"] });
console.log(linter.hasFlag("x_feature")); // true
RuleTester
eslint.RuleTester 是一个用于编写 ESLint 规则测试的实用程序。它在 ESLint 附带的捆绑规则中内部使用，也可以由插件使用。
使用示例
"use strict";
const rule = require("../../../lib/rules/my-rule"),
RuleTester = require("eslint").RuleTester;
const ruleTester = new RuleTester();
ruleTester.run("my-rule", rule, {
valid: [
{
code: "var foo = true",
options: [{ allowFoo: true }]
}
],
invalid: [
{
code: "var invalidVariable = true",
errors: [{ message: "Unexpected invalid variable." }]
},
{
code: "var invalidVariable = true",
errors: [{ message: /^Unexpected.+variable/ }]
}
]
});
RuleTester 构造函数接受一个可选的对象参数，该参数可用于为您的测试用例指定默认值。例如，如果您的所有测试用例都使用 ES2015，则可以将其设置为默认值
const ruleTester = new RuleTester({ languageOptions: { ecmaVersion: 2015 } });
RuleTester#run() 方法用于运行测试。它应该传递以下参数：
- 规则的名称（字符串）
- 规则对象本身（参见 “规则工作”）
- 一个包含
valid和invalid属性的对象，每个属性都是一个包含测试用例的数组。
测试用例是一个具有以下属性的对象：
name（字符串，可选）：用于测试用例的名称，以便于查找code（字符串，必需）：规则应在其上运行的源代码options（数组，可选）：传递给规则的选项。规则严重性不应包含在此列表中。before（函数，可选）：在测试用例之前执行的函数。after（函数，可选）：无论测试用例的结果如何，在测试用例之后执行的函数。filename（字符串，可选）：给定用例的文件名（对于对文件名进行断言的规则很有用）。only（布尔值，可选）：在受支持的测试框架中专门运行此用例进行调试。
除了上述属性外，无效测试用例还可以具有以下属性：
-
errors（数字或数组，必需）：断言规则在运行此代码时预期产生的错误的一些属性。如果这是一个数字，则断言产生的错误数量。否则，这应该是一个对象列表，每个对象都包含有关单个报告错误的信息。以下属性可用于错误（除非另有说明，否则所有属性都是可选的）message(字符串/正则表达式): 错误消息。必须提供此属性或messageIdmessageId(字符串): 错误的 ID。必须提供此属性或message。详情请参见 使用 messageId 测试错误data(对象): 可与messageId结合使用的占位符数据type(字符串): (已弃用: 此属性将在 ESLint 的未来版本中移除。) 报告的 AST 节点的类型line(数字): 报告位置的基于 1 的行号column(数字): 报告位置的基于 1 的列号endLine(数字): 报告位置结束处的基于 1 的行号endColumn(数字): 报告位置结束处的基于 1 的列号suggestions(数组): 包含建议详细信息的对象数组，用于检查。如果规则生成建议，则需要此属性。详情请参见 测试建议
如果提供字符串而不是对象作为错误，则该字符串用于断言错误的
message。 -
output(字符串，如果规则修复代码则为必填): 断言使用此规则进行一次自动修复传递时（例如，使用--fix命令行标志）将产生的输出。如果此值为null或省略，则断言没有报告的问题建议自动修复。
测试用例的任何其他属性都将直接传递给 linter 作为配置选项。例如，测试用例可以具有 languageOptions 属性来配置解析器行为
{
code: "let foo;",
languageOptions: { ecmaVersion: 2015 }
}
如果有效的测试用例仅使用 code 属性，则可以选择将其作为包含代码的字符串提供，而不是包含 code 键的对象。
使用 messageId 测试错误
如果正在测试的规则使用 messageId，则可以在测试用例中使用 messageId 属性来断言报告错误的 messageId，而不是其 message。
{
code: "let foo;",
errors: [{ messageId: "unexpected" }]
}
对于带有占位符的消息，测试用例还可以使用 data 属性来额外断言报告错误的 message。
{
code: "let foo;",
errors: [{ messageId: "unexpected", data: { name: "foo" } }]
}
请注意，测试用例中的 data 不会断言传递给 context.report 的 data。相反，它用于形成预期的消息文本，然后将其与接收到的 message 进行比较。
测试修复
可以通过使用无效测试用例的 output 属性来测试应用修复程序的结果。只有当您期望将修复程序应用于指定的 code 时，才应使用 output 属性；如果代码预计没有更改，则可以安全地省略 output。这是一个例子
ruleTester.run("my-rule-for-no-foo", rule, {
valid: [],
invalid: [{
code: "var foo;",
output: "var bar;",
errors: [{
messageId: "shouldBeBar",
line: 1,
column: 5
}]
}]
})
在此无效测试用例的末尾，RuleTester 期望应用修复程序，从而导致代码从 var foo; 更改为 var bar;。如果应用修复程序后的输出不匹配，则测试失败。
测试建议
可以通过在错误对象上定义 suggestions 键来测试建议。如果这是一个数字，则断言为错误提供的建议数量。否则，这应该是一个对象数组，每个对象都包含有关单个提供的建议的信息。可以使用以下属性
desc(字符串): 建议的desc值。必须提供此属性或messageIdmessageId(字符串): 使用messageId的建议的建议messageId值。必须提供此属性或descdata(对象): 可与messageId结合使用的占位符数据。output(字符串，必填): 表示将建议修复应用于输入代码的结果的代码字符串
示例
ruleTester.run("my-rule-for-no-foo", rule, {
valid: [],
invalid: [{
code: "var foo;",
errors: [{
suggestions: [{
desc: "Rename identifier 'foo' to 'bar'",
output: "var bar;"
}]
}]
}]
})
建议测试对象中的 messageId 和 data 属性的工作方式与错误测试对象中的相同。详情请参见 使用 messageId 测试错误。
ruleTester.run("my-rule-for-no-foo", rule, {
valid: [],
invalid: [{
code: "var foo;",
errors: [{
suggestions: [{
messageId: "renameFoo",
data: { newName: "bar" },
output: "var bar;"
}]
}]
}]
})
自定义 RuleTester
RuleTester 依赖于两个函数来运行测试：describe 和 it。这些函数可以来自多个地方
-
如果
RuleTester.describe和RuleTester.it已设置为函数值，则RuleTester将使用RuleTester.describe和RuleTester.it来运行测试。您可以使用此功能自定义RuleTester的行为，以匹配您正在使用的测试框架。如果
RuleTester.itOnly已设置为函数值，则RuleTester将调用RuleTester.itOnly而不是RuleTester.it来运行only: true的用例。如果RuleTester.itOnly未设置但RuleTester.it有一个only函数属性，则RuleTester将回退到RuleTester.it.only。 -
否则，如果
describe和it作为全局变量存在，则RuleTester将使用globalThis.describe和globalThis.it来运行测试，并使用globalThis.it.only来运行only: true的用例。这允许RuleTester在使用像 Mocha 这样的框架时无需任何额外配置即可工作。 -
否则，
RuleTester#run将简单地按顺序执行所有测试，如果其中一个测试失败，则会抛出错误。这意味着您可以简单地使用Node.js执行调用RuleTester.run的测试文件，而无需测试框架。
RuleTester#run 使用两个参数调用 describe 函数：描述规则的字符串和回调函数。回调函数使用描述测试用例的字符串和测试函数调用 it 函数。如果测试通过，则测试函数将成功返回；如果测试失败，则会抛出错误。only 的签名与 it 相同。即使某些用例具有 only: true，RuleTester 也会为每个用例调用 it 或 only，并且测试框架负责实现测试用例的排他性。（请注意，这是使用像 Mocha 这样的框架时测试套件的标准行为；此信息仅在您计划自定义 RuleTester.describe、RuleTester.it 或 RuleTester.itOnly 时才相关。）
自定义 RuleTester 的示例
"use strict";
const RuleTester = require("eslint").RuleTester,
test = require("my-test-runner"),
myRule = require("../../../lib/rules/my-rule");
RuleTester.describe = function(text, method) {
RuleTester.it.title = text;
return method.call(this);
};
RuleTester.it = function(text, method) {
test(RuleTester.it.title + ": " + text, method);
};
// then use RuleTester as documented
const ruleTester = new RuleTester();
ruleTester.run("my-rule", myRule, {
valid: [
// valid test cases
],
invalid: [
// invalid test cases
]
})