.config/coc/extensions/node_modules/coc-prettier/node_modules/stylelint/docs/developer-guide/rule-testers.md

   1 # Rule testers
   2
   3 stylelint rules require *a lot* of tests. So we've built a specialized stylelint rule testing format to speed up the mass production of consistent, effective rule tests.
   4
   5 There is a schema for describing tests, and a function for creating "rule testers" that interpret that schema using a test framework (e.g. tape or Mocha).
   6
   7 When developing plugins, you can use the following rule testers or create your own.
   8
   9 -   stylelint-test-rule-tape
  10 -   stylelint-test-rule-mocha
  11 -   stylelint-test-rule-ava
  12
  13 ## Using a rule tester
  14
  15 To use the rule tester of your choice, do the following:
  16
  17 ```js
  18 // `testRule` = the imported rule tester
  19 testRule(rule, testGroupDescription)
  20 ```
  21
  22 `rule` is just the rule that you are testing (a function).
  23
  24 `testGroupDescription` is an object fitting the following schema.
  25
  26 ### The test group schema
  27
  28 Each test group object describes a set of test-cases for a certain rule with a certain configuration.
  29
  30 Required properties:
  31
  32 -   `ruleName` {string}: The name of the rule. Used in generated test-case descriptions.
  33 -   `config` {any}: The rule's configuration for this test group. Should match the rule configuration format you'd use in `.stylelintrc`.
  34 -   `accept` {array}: An array of objects describing test cases that *should not violate the rule*. Each object has these properties:
  35     -   `code` {string}: The source CSS to check.
  36     -   `description` {string}: *Optional.* A description of the case.
  37     -   `only` {boolean}: If `true`, run only this test case.
  38 -   `reject` {array}: An array of objects describing test cases that *should violate the rule once*. Each object has these properties:
  39     -   `code` {string}: The source CSS to check.
  40     -   `message` {string}: The message of the expected violation.
  41     -   `line` {number}: *Optional but recommended.* The expected line number of the violation. If this is left out, the line won't be checked.
  42     -   `column` {number}: *Optional but recommended.* The expected column number of the violation. If this is left out, the column won't be checked.
  43     -   `description` {string}: *Optional.* A description of the case.
  44     -   `only` {boolean}: If `true`, run only this test case.
  45     -   `fixed` {string}: *Required if test schema has `fix` enabled.* Result of autofixing against `code` property.
  46
  47 Optional properties:
  48
  49 -   `syntax` {"css"|"less"|"scss"|"sugarss"}: Defaults to `"css"`. Other settings use special parsers.
  50 -   `skipBasicChecks` {boolean}: Defaults to `false`. If `true`, a few rudimentary checks (that should almost always be included) will not be performed. You can check those out in `lib/testUtils/basicChecks.js`.
  51 -   `preceedingPlugins` {array}: An array of PostCSS plugins that should be run before the CSS is tested.
  52 -   `fix` {boolean}: Defaults to `false`. If `true`, every `reject` test-case will be tested for autofixing functionality. *Required if rule has autofixing.*
  53
  54 ## Creating a rule tester
  55
  56 stylelint itself exposes a means of creating rule testers with just about any testing framework.
  57
  58 ```js
  59 var testRule = stylelint.createRuleTester(equalityCheck)
  60 ```
  61
  62 Pass in an `equalityCheck` function. Given some information, this checker should use whatever test runner you like to perform equality checks.
  63
  64 The `equalityCheck` function should accept two arguments:
  65
  66 -   `processCss` {Promise}: A Promise that resolves with an array of comparisons that you need to check (documented below).
  67 -   `context` {object}: An object that contains additional information you may need:
  68     -   `caseDescription` {string}: A description of the test case as  whole. It will end up printing like something this:
  69     ```bash
  70     > rule: value-list-comma-space-before
  71     > config: "always-single-line"
  72     > code: "a { background-size: 0 ,0;\n}"
  73     ```
  74     -   `comparisonCount` {number}: The number of comparisons that will need to be performed (e.g. useful for tape).
  75     -   `completeAssertionDescription` {string}: While each individual comparison may have its own description, this is a description of the whole assertion (e.g. useful for Mocha).
  76     -   `only` {boolean}: If `true`, the test runner should only run this test case (e.g. `test.only` in tape, `describe.only` in Mocha).
  77
  78 `processCss` is a Promise that resolves with an array of comparisons. Each comparison has the following properties:
  79
  80 -   `actual` {any}: Some actual value.
  81 -   `expected` {any}: Some expected value.
  82 -   `description` {string}: A (possibly empty) description of the comparison.
  83
  84 Within the `equalityCheck` function, you need to ensure that you do the following:
  85
  86 -   Set up the test case.
  87 -   When `processCss` resolves, loop through every comparison.
  88 -   For each comparison, make an assertion checking that `actual === expected`.
  89
  90 A `testRule` function (as described above) is returned.