Stylelint testing utils

Appearance

createTestRule ​

This is a function that allows to create sets of tests bound to a specific rule.
You should always pass ruleName into it, and you can also configure some useful defaults or overwrite those described in createTestUtils for a particular rule.

Minimal use case ​

Note

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

plugins is a required property only if you have not specified it in createTestUtils.

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

const { ruleName } = yourRule;
const testRule = createTestRule({ ruleName }); 

testRule({
  // ...
});

Options ​

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

ruleName ​

Info

This is the only required option (if you have specified plugins in createTestUtils).
All others are optional, but can improve your DX.

The name of the rule that is being tested.

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

plugins ​

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

Required if plugins is not specified when declaring createTestUtils.

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, if specified, appended to these rules.

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.

customSyntax ​

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

Show original description

Maps to Stylelint's customSyntax configuration property, has the same signature.

autoStripIndent ​

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

Show original description

Controls whether indentation should be automatically stripped out of code blocks.

ts
/**
 * @default false
 */
type AutoStripIndent = boolean;
Um, why?

It can be quite tedious to calculate error positions when testing complex multi-line rules.
Let's pretend we have the following sample code and we expect to see an error highlighting on the .another-component selector:

ts
{
  description: 'Side-effect within `@media`-query on the root level',
  code: `
    .the-component {}

    @media (max-width: 320px) {
      .another-component {}
    }
  `,
}

You would say that the error should start on line 4 and column 3, wouldn't you?
But in fact, for this particular code block, the error will start on line 5 and column 9!

This is because the input is a string that contains all linebreaks and indentation:

text
`
      .the-component {}

      @media (max-width: 320px) {
        .another-component {}
      }
    `

Not very similar to how our CSS usually looks like.
Imagine you are designing a rule that interacts with indentation...

With the autoStripIndent option enabled, all code blocks automatically remove the start/end spaces as well as the extra indentation, so the string becomes exactly what we would see in the CSS file:

text
.the-component {}

@media (max-width: 320px) {
  .another-component {}
}