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 对象数组完成的 promise。
◆ 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[]>)
一个 promise，它将被 LintResult 对象的数组填充。为了使此方法与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>)
一个 promise，它将被一个 LoadedFormatter 对象填充。
◆ 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)
错误消息。messageId(string | undefined)
lint 错误的消息 ID。如果规则不使用消息 ID，则此属性未定义。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; messageId?: string; data?: object }[] | 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相同。messageId(string | undefined)
与 LintMessage 类型中的messageId相同。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; messageId?: string; data?: object }[] | 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时，代码检查器不会生成lint结果的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- 应输出的消息。messageId- 用于生成消息的消息ID（如果规则未使用消息ID，则省略此属性）。nodeType- （已弃用：此属性将在ESLint的未来版本中删除。）报告问题的节点或标记类型。ruleId- 触发消息的规则的ID（如果fatal为true，则为null）。severity- 1或2，具体取决于您的配置。endColumn- 发生错误的范围的结束列（如果不是范围，则省略此属性）。endLine- 发生错误的范围的结束行（如果不是范围，则省略此属性）。fix- 描述问题修复的对象（如果无法修复，则省略此属性）。suggestions- 描述编辑器可以以编程方式启用的可能的lint修复的对象数组（有关详细信息，请参阅规则工作文档）。
您可以通过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()
此方法用于获取花费在（解析、修复、代码检查）文件上的时间。请参阅Stats对象的times属性。
Linter#getFixPassCount()
此方法用于获取进行的自动修复传递次数。请参阅Stats对象的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（字符串/正则表达式）：错误消息。必须提供此属性或messageId。messageId（字符串）：错误的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 相同。RuleTester 即使某些用例具有 only: true，也会为每个用例调用 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
]
})