RuleTester

Test framework for ESLint rules

The RuleTester class is used to test ESLint rules. It integrates with testing frameworks like Mocha and Jest to provide a structured way to write and run rule tests.

Constructor

const { RuleTester } = require("eslint");
const ruleTester = new RuleTester(config);

config · object

Default configuration to use for all test cases.

Show properties

languageOptions · object

Language options for parsing (ecmaVersion, sourceType, etc.).

rules · object

Default rule configurations.

settings · object

Shared settings for rules.

Instance Methods

run()

Runs test cases for a rule.

ruleTester.run(ruleName, rule, tests);

ruleName · string · required

The name of the rule being tested.

rule · object · required

The rule object with a create() method.

tests · object · required

Show properties

valid · Array<string | ValidTestCase> · required

Array of test cases that should pass without errors.

invalid · InvalidTestCase[] · required

Array of test cases that should produce errors.

Test Case Types

ValidTestCase

A test case expected to pass without errors.

code · string · required

The code to test.

name · string

Name for the test case (displayed in test output).

options · any[]

Options to pass to the rule.

languageOptions · object

Language options for this test case.

Show properties

ecmaVersion · number | 'latest'

ECMAScript version (e.g., 2020, “latest”).

sourceType · 'script' | 'module' | 'commonjs'

The source type of the code.

parserOptions · object

Additional parser options.

settings · object

Settings for this test case.

filename · string

The fake filename for the test case.

only · boolean

Run only this test case (requires framework support).

InvalidTestCase

A test case expected to produce errors.

code · string · required

The code to test.

errors · number | Array<TestCaseError> · required

Expected errors. Can be a count or array of error objects.

output · string | null

Expected code after autofixes. Use null to assert no autofix.

name · string

Name for the test case.

options · any[]

Options to pass to the rule.

languageOptions · object

Language options for this test case.

settings · object

Settings for this test case.

filename · string

The fake filename for the test case.

only · boolean

Run only this test case.

TestCaseError

Describes an expected error in an invalid test case.

message · string | RegExp

Expected error message or pattern.

messageId · string

Expected message ID from rule’s meta.messages.

data · object

Expected data used to fill the message template.

line · number

Expected 1-based line number.

column · number

Expected 1-based column number.

endLine · number

Expected 1-based end line number.

endColumn · number

Expected 1-based end column number.

suggestions · object[]

Expected suggestion objects.

Static Methods

RuleTester.setDefaultConfig()

Sets the default configuration for all RuleTester instances.

RuleTester.setDefaultConfig(config);

config · object · required

The default configuration object.

RuleTester.resetDefaultConfig()

Resets the default configuration to the initial defaults.

RuleTester.resetDefaultConfig();

RuleTester.describe()

Sets the describe function for grouping tests (automatically detected).

RuleTester.describe(describeFn);

describeFn · function · required

The describe function from your test framework.

RuleTester.it()

Sets the it function for individual tests (automatically detected).

RuleTester.it(itFn);

itFn · function · required

The it function from your test framework.

Examples

Basic Test

const { RuleTester } = require("eslint");
const rule = require("../rules/no-console");

const ruleTester = new RuleTester({
  languageOptions: {
    ecmaVersion: 2020,
    sourceType: "module"
  }
});

ruleTester.run("no-console", rule, {
  valid: [
    "console.info('test');",
    "console.warn('test');"
  ],
  invalid: [
    {
      code: "console.log('test');",
      errors: [{ message: "Unexpected console statement." }]
    }
  ]
});

With Message IDs

const { RuleTester } = require("eslint");
const rule = require("../rules/prefer-const");

const ruleTester = new RuleTester();

ruleTester.run("prefer-const", rule, {
  valid: [
    "const x = 1;",
    "let x = 1; x = 2;"
  ],
  invalid: [
    {
      code: "let x = 1;",
      output: "const x = 1;",
      errors: [
        {
          messageId: "useConst",
          data: { name: "x" },
          line: 1,
          column: 5
        }
      ]
    }
  ]
});

With Options

const { RuleTester } = require("eslint");
const rule = require("../rules/quotes");

const ruleTester = new RuleTester();

ruleTester.run("quotes", rule, {
  valid: [
    {
      code: "var x = 'test';",
      options: ["single"]
    },
    {
      code: 'var x = "test";',
      options: ["double"]
    }
  ],
  invalid: [
    {
      code: 'var x = "test";',
      output: "var x = 'test';",
      options: ["single"],
      errors: [
        {
          message: "Strings must use singlequote.",
          line: 1
        }
      ]
    }
  ]
});

With Suggestions

const { RuleTester } = require("eslint");
const rule = require("../rules/no-unused-vars");

const ruleTester = new RuleTester();

ruleTester.run("no-unused-vars", rule, {
  valid: [
    "var x = 1; console.log(x);"
  ],
  invalid: [
    {
      code: "var x = 1;",
      errors: [
        {
          messageId: "unusedVar",
          data: { name: "x" },
          suggestions: [
            {
              messageId: "removeVar",
              output: ""
            }
          ]
        }
      ]
    }
  ]
});

Best Practices

Use Named Test Cases

Add a name property to test cases for better test output:

ruleTester.run("my-rule", rule, {
  valid: [
    {
      name: "allows const declarations",
      code: "const x = 1;"
    }
  ],
  invalid: [
    {
      name: "reports var declarations",
      code: "var x = 1;",
      errors: [{ messageId: "useConst" }]
    }
  ]
});

Test All Error Properties

Verify message IDs, data, and locations:

{
  code: "var x = 1;",
  errors: [
    {
      messageId: "useConst",
      data: { name: "x" },
      line: 1,
      column: 5,
      endLine: 1,
      endColumn: 6
    }
  ]
}

Test Autofixes

Always specify the expected output for fixable rules:

{
  code: "var x = 1;",
  output: "const x = 1;",
  errors: [{ messageId: "useConst" }]
}

Use Null for No Autofix

Set output: null to assert the rule doesn’t provide a fix:

{
  code: "var x = 1;",
  output: null,
  errors: [{ messageId: "noVar" }]
}