@jhae/stylelint-config-verifier/README.md

A Stylelint configuration tester for Jest that helps you verify your defined rules.

![Version](https://img.shields.io/npm/v/%40jhae/stylelint-config-verifier?label=Version&labelColor=%23404850&color=blue)
![License](https://img.shields.io/github/license/jhae-de/stylelint-config-verifier?label=License&labelColor=%23404850&color=blue)
![Downloads](https://img.shields.io/npm/dt/%40jhae%2Fstylelint-config-verifier?label=Downloads&labelColor=%23404850&color=blue)
![Tests](https://img.shields.io/github/actions/workflow/status/jhae-de/stylelint-config-verifier/analyze.yaml?label=Tests&labelColor=%23404850)
![Coverage](https://img.shields.io/codecov/c/github/jhae-de/stylelint-config-verifier/main?label=Coverage&labelColor=%23404850)

# Stylelint Config Verifier

Does your [Stylelint](https://github.com/stylelint/stylelint) configuration meet your expectations? Easily test
individual rules with [Jest](https://github.com/jestjs/jest) using code snippets and ensure that errors and warnings are
being reported correctly.

## Installation

Using npm:

```shell
npm install --save-dev @jhae/stylelint-config-verifier
```

## Usage

### With inline code

Example Stylelint configuration file:

```yaml
rules:
  at-rule-disallowed-list:
    - debug
    - import
```

Verifying the `at-rule-disallowed-list` rule configuration:

```javascript
import { ConfigVerifier } from '@jhae/stylelint-config-verifier';

new ConfigVerifier().verify(
  // Pass the name of the rule.
  'at-rule-disallowed-list',

  // Describe one or more test cases.
  {
    // Give the test case a name.
    name: 'Disallow @debug rule',

    // Place the code to be tested against the configuration file here.
    code: '@debug "";',

    // Define the expectation.
    expect: {
      // Whether Stylelint should report an error or not.
      errored: true,

      // The messages that Stylelint should report.
      messages: ['Unexpected at-rule "debug"'],

      // The severities that Stylelint should report for each message.
      severities: ['error'],
    },
  },
  {
    name: 'Disallow @import rule',
    code: `
      @import "test-1.css";
      @import "test-2.css";
    `,
    expect: {
      errored: true,
      messages: ['Unexpected at-rule "import"', 'Unexpected at-rule "import"'],
      severities: ['error', 'error'],
    },
  },
  {
    // The expectation can be omitted if Stylelint should not report errors.
    name: 'Allow @use rule',
    code: '@use "test.scss";',
  },
);
```

The verification result:

```shell
Rule 'at-rule-disallowed-list'
  ✓ Disallow @debug rule (1 ms)
  ✓ Disallow @import rule (1 ms)
  ✓ Allow @use rule (1 ms)
```

### With a file

It is also possible to pass a file to the test case. This is useful for testing overrides, for example.

Example Stylelint configuration file:

```yaml
rules:
  at-rule-disallowed-list: null

overrides:
  - files:
      - '**/*.scss'
    rules:
      at-rule-disallowed-list:
        - import
```

The SCSS file, for example `at-rule-disallowed-list.scss`:

```scss
@import 'test.css';
```

Verifying the `at-rule-disallowed-list` rule configuration:

```javascript
import { ConfigVerifier } from '@jhae/stylelint-config-verifier';

new ConfigVerifier().verify('at-rule-disallowed-list', {
  name: 'Disallow @import rule in SCSS files',

  // Pass the file instead of inline code.
  file: 'at-rule-disallowed-list.scss',

  expect: {
    errored: true,
    messages: ['Unexpected at-rule "@import"'],
    severities: ['error'],
  },
});
```

### Specifying the Stylelint configuration file

By default, the Stylelint configuration file is detected automatically as described in
the [Stylelint documentation](https://stylelint.io/user-guide/configure). If needed, you can override this behavior by
passing the path to the configuration file to the constructor.

```javascript
import { ConfigVerifier } from '@jhae/stylelint-config-verifier';

new ConfigVerifier('path/to/stylelint.config.js').verify();
```

---

Check out the [Standard SCSS Stylelint Config](https://github.com/jhae-de/stylelint-config-standard-scss) tests for more
examples.