Stylelint testing utils

Appearance

testRuleConfig ​

The function for testing rule configurations returned by the createTestRuleConfig factory.

Minimal use case ​

Note

It is assumed that you have declared the createTestRuleConfig function globally as specified in the Guide section of the documentation and the plugins key is present within createTestUtils.

ts
import { yourRule } from './your-rule.ts';

const { ruleName } = yourRule;
const testRuleConfig = createTestRuleConfig({ ruleName });

testRuleConfig({
  accept: [
    {
      description: 'Primary option is "always"',
      config: 'always',
    },
    {
      description: 'Secondary option is a string as expected',
      config: ['always', '.foo'],
    },
  ],
  reject: [
    {
      description: 'Primary option is an unexpected string',
      config: 'just-a-random-one',
    },
    {
      description: 'Secondary option is not a string',
      config: ['always', true],
    },
  ],
});

Options ​

You can always see the actual options in the source code here.

ruleName ​

The same option as described in createTestRuleConfig > Options > ruleName but takes precedence over it if specified, allowing to overwrite the defaults for a particular rule.

Note

It is recommended to define ruleName within createTestRuleConfig function to reduce the boilerplate code. The option only exists to ensure that the project can be a drop-in replacement for an existing solutions for testing Stylelint plugins.

Show original description

The name of the rule that is being tested.

Used for output in the console, and for binding the config property of the testRuleConfig function to a rule from the plugins list.

plugins ​

The same option as described in createTestUtils > Options > plugins but takes precedence over values from both createTestRuleConfig and createTestUtils when specified.

Note

It is recommended to define plugins within createTestUtils or createTestRuleConfig functions to reduce the boilerplate code. The option only exists to ensure that the project can be a drop-in replacement for an existing solutions for testing Stylelint plugins.

Show original description

Maps to Stylelint's plugins configuration property, has the same signature.
Expected either the path to the JS file that provides your rule, or its contents, or an array of such elements in the case you are testing a plugin pack.

extraRules ​

The same option as described in createTestUtils > Options > extraRules, but is merged after those rules, so a rule with the same name replaces the value from createTestUtils.

Show original description

Object in form compatible with Stylelint's rules property, that allows to run stylelint with extra rules in addition to the one being tested.

description ​

Description of the test group.
It is displayed in the console and makes it easier to identify the test when necessary.
If omitted, it is displayed as group #N by default; line-in-file uses the source line instead.

ts
testRuleConfig({
  description: 'Primary option',
  accept: [
    {
      description: 'Keyword "always"',
      config: 'always'
    },
    {
      description: 'Keyword "never"',
      config: 'always'
    },
  ],
});
bash
✓ `{rule-name}` configs: Primary option (2)
  ✓ accept (2)
    ✓ Keyword "always"
    ✓ Keyword "never"

accept & reject ​

An array of rule configurations that should produce no invalid-option warnings or at least one invalid-option warning, respectively.
See more info about test cases in Test cases section below.

skip & only ​

Controls whether to skip the group of tests or run only that group.

ts
// Only tests of this group will be run because of the `only` flag
testRuleConfig({
  description: 'Primary option',
  only: true,
  accept: [
    {
      description: 'Keyword "always"',
      config: 'always'
    },
    {
      description: 'Keyword "never"',
      config: 'always'
    },
  ],
});

testRuleConfig({
  description: 'Secondary options',
  accept: [
    {
      description: 'Key "ignore" as a string',
      config: ['always', { ignore: 'foo' }]
    },
    {
      description: 'Key "ignore" as an array of string',
      config: ['always', { ignore: ['foo', 'bar'] }]
    },
  ],
});

Test cases ​

There are two types of tests:

  • accept (rule configurations that must produce no invalid-option warnings);
  • reject (rule configurations that must produce at least one invalid-option warning).

They are located in the accept and reject keys of the testRuleConfig() options respectively.

Each group of tests described by the testRuleConfig() function must contain at least one test - no matter whether it is accepted or rejected.

Both the accepted test case and the rejected one have the same set of properties described below:

config ​

Each test requires a config property: the value supplied to the tested rule in Stylelint's rules configuration.
A configuration test without config just doesn't make sense.

ts
testRuleConfig({
  accept: [
    {
      description: 'Keyword "always"',
      config: 'always'
    },
    {
      description: 'Keyword "always" with secondary option',
      config: ['always', { ignore: 'foo' }]
    },
  ],
});
ts
// .stylelintrc.js
export default {
  rules: {
    'your-rule/foo': 'always',
    // or
    'your-rule/foo': ['always', { ignore: ['foo'] }],
  }
}

description ​

A test can have a description - it is displayed in the console and makes it easier to find the test if necessary.
If no description is provided, then instead of description will be displayed either the test sequence number (by default) or its config, depending on the testCaseWithoutDescriptionAppearance option.

ts
testRuleConfig({
  accept: [
    {
      description: 'Keyword "always"',
      config: 'always'
    },
    {
      // description: 'no description here',
      config: 'always'
    },
  ],
});
bash
✓ `{rule-name}` configs: group №1 (2)
  ✓ accept (2)
    ✓ Keyword "always"
    ✓ Accept test case №2

skip & only flags ​

Controls whether to skip the test or run the only test.

ts
testRuleConfig({
  accept: [
    // Only this test will be run because of `only` flag.
    { 
      only: true, 
      description: 'Keyword "always"', 
      config: 'always', 
    }, 
    {
      description: 'Keyword "never"',
      config: 'never',
    },
  ],
});

Additional features ​

The function can be called using its own skip and only methods to make these modifiers more visible when using folding.

ts
testRuleConfig.skip({ 
  accept: [
    {
      description: 'Keyword "never"',
      config: 'never',
    },
  ],
});

// The same as:

testRuleConfig({ 
  skip: true, 
  accept: [
    {
      description: 'Keyword "never"',
      config: 'never',
    },
  ],
});