jest-preset-stylelint 4.2.0 → 5.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![NPM version](https://img.shields.io/npm/v/jest-preset-stylelint.svg)](https://www.npmjs.org/package/jest-preset-stylelint) [![Build Status](https://github.com/stylelint/jest-preset-stylelint/workflows/CI/badge.svg)](https://github.com/stylelint/jest-preset-stylelint/actions)
 
-[Jest](https://facebook.github.io/jest/) preset for [stylelint](https://github.com/stylelint) plugins.
+[Jest](https://facebook.github.io/jest/) preset for [Stylelint](https://github.com/stylelint) plugins.
 
 ## Installation
 
@@ -24,10 +24,10 @@ Add the preset to your `jest.config.js` or `jest` field in `package.json`:
 
 Optionally, you can avoid specifying `plugins` in every schema by defining your own setup file to configure the `testRule` function. This is useful if you have many tests. There are two additional steps to do this:
 
-1. Create `jest.setup.js` in the root of your project. Provide [`plugins`](#plugins-arraystring) option to `getTestRule()`:
+1. Create `jest.setup.js` in the root of your project. Provide `plugins` option to `getTestRule()`:
 
    ```js
-   const getTestRule = require("jest-preset-stylelint/getTestRule");
+   const { getTestRule } = require("jest-preset-stylelint");
 
    global.testRule = getTestRule({ plugins: ["./"] });
    ```
@@ -75,7 +75,9 @@ testRule({
       description: "camel case class selector",
       message: messages.expected(),
       line: 1,
-      column: 1
+      column: 1,
+      endLine: 1,
+      endColumn: 8
     },
     {
       code: ".MyClass,\n.MyOtherClass {}",
@@ -85,12 +87,16 @@ testRule({
         {
           message: messages.expected(),
           line: 1,
-          column: 1
+          column: 1,
+          endLine: 1,
+          endColumn: 8
         },
         {
           message: messages.expected(),
           line: 2,
-          column: 1
+          column: 1,
+          endLine: 2,
+          endColumn: 13
         }
       ]
     }
@@ -100,117 +106,7 @@ testRule({
 
 ## Schema properties
 
-### `accept` \[array\<Object\>\]
-
-Accept test cases.
-
-### `config` \[array\]
-
-Config to pass to the rule.
-
-### `fix` \[boolean\]
-
-Default: `false` (Optional).
-
-Turn on autofix.
-
-### `plugins` \[array\<string\>\]
-
-Maps to Stylelint's [`plugins` configuration property](https://stylelint.io/user-guide/configure#plugins).
-
-Path to the file that exports the plugin object, relative to the root. Usually it's the same path as a `main` property in plugin's `package.json`.
-
-If you're testing a plugin pack, it's the path to the file that exports the array of plugin objects.
-
-Optional, if `plugins` option was passed to advanced configuration with `getTestRule()`.
-
-### `reject` \[array\<Object\>\]
-
-Reject test cases.
-
-### `ruleName` \[string\]
-
-Name of the rule being tested. Usually exported from the plugin.
-
-### `skipBasicChecks` \[boolean\]
-
-Default: `false` (Optional).
-
-Skip [basic checks](https://github.com/stylelint/stylelint/blob/master/lib/testUtils/basicChecks.js), e.g. an empty source.
-
-### `customSyntax` \<string\>
-
-Maps to Stylelint's [`customSyntax` option](https://stylelint.io/user-guide/usage/options#customsyntax).
-
-### `codeFilename` \<string\>
-
-Maps to Stylelint's [`codeFilename` option](https://stylelint.io/user-guide/usage/options#codefilename).
-
-## Shared test case properties
-
-Used within both `accept` and `reject` test cases.
-
-### `code` \[string\]
-
-The code of the test case.
-
-### `description` \[string\]
-
-Optional.
-
-Description of the test case.
-
-### `skip` \[boolean\]
-
-Default: `false` (Optional).
-
-Maps to Jest's [test.skip](https://jestjs.io/docs/en/api#testskipname-fn).
-
-### `only` \[boolean\]
-
-Default: `false` (Optional).
-
-Maps to Jest's [test.only](https://jestjs.io/docs/en/api#testonlyname-fn-timeout).
-
-## Reject test case properties
-
-Use the `warnings` property, rather than `message`, `line` and `column`, if the test case is expected to produce more than one warning.
-
-### `column` \[number\]
-
-Optional.
-
-Expected column number of the warning.
-
-### `fixed` \[string\]
-
-Optional if `fix` isn't `true`.
-
-Expected fixed code of the test case.
-
-### `line` \[number\]
-
-Optional.
-
-Expected line number of the warning.
-
-### `message` \[string\]
-
-Optional if `warnings` is used.
-
-Expected message from the test case. Usually exported from the plugin.
-
-### `unfixable` \[boolean\]
-
-Default: `false` (Optional).
-
-Don't check the `fixed` code.
-
-### `warnings` \[array\<Object\>\]
-
-Optional if `message` is used.
-
-Warning Objects containing expected `message`, `line` and `column`.
+See the [type definitions](index.d.ts).
 
 ## [Changelog](CHANGELOG.md)
 

package/getTestRule.js

@@ -2,35 +2,15 @@
 
 const util = require('util');
 // eslint-disable-next-line node/no-unpublished-require -- Avoid auto-install of `stylelint` peer dependency.
-const { basicChecks, lint } = require('stylelint');
+const { lint } = require('stylelint');
 
 /**
- * @typedef {Object} TestCase
- * @property {string} code
- * @property {string} [description]
- * @property {boolean} [only]
- * @property {boolean} [skip]
+ * @typedef {import('.').TestCase} TestCase
+ * @typedef {import('.').TestSchema} TestSchema
  */
 
-/**
- * @typedef {Object} TestSchema
- * @property {string} ruleName
- * @property {any} config
- * @property {TestCase[]} accept
- * @property {TestCase[]} reject
- * @property {string | string[]} plugins
- * @property {boolean} [skipBasicChecks]
- * @property {boolean} [fix]
- * @property {Syntax} [customSyntax] - PostCSS Syntax (https://postcss.org/api/#syntax)
- * @property {string} [codeFilename]
- * @property {boolean} [only]
- * @property {boolean} [skip]
- */
-
-function getTestRule(options = {}) {
-	/**
-	 * @param {TestSchema} schema
-	 */
+/** @type {import('.').getTestRule} */
+module.exports = function getTestRule(options = {}) {
 	return function testRule(schema) {
 		describe(`${schema.ruleName}`, () => {
 			const stylelintConfig = {
@@ -40,15 +20,9 @@ function getTestRule(options = {}) {
 				},
 			};
 
-			let passingTestCases = schema.accept || [];
-
-			if (!schema.skipBasicChecks) {
-				passingTestCases = passingTestCases.concat(basicChecks);
-			}
-
 			setupTestCases({
 				name: 'accept',
-				cases: passingTestCases,
+				cases: schema.accept,
 				schema,
 				comparisons: (testCase) => async () => {
 					const stylelintOptions = {
@@ -95,6 +69,7 @@ function getTestRule(options = {}) {
 					(testCase.warnings || [testCase]).forEach((expected, i) => {
 						const warning = actualWarnings[i];
 
+						// @ts-expect-error -- This is our custom matcher.
 						expect(expected).toHaveMessage();
 
 						expect(warning.text).toBe(expected.message);
@@ -106,6 +81,16 @@ function getTestRule(options = {}) {
 						if (expected.column !== undefined) {
 							expect(warning.column).toBe(expected.column);
 						}
+
+						if (expected.endLine !== undefined) {
+							// @ts-expect-error -- TODO: `warning.endLine` is not implemented. See stylelint/stylelint#5725
+							expect(warning.endLine).toBe(expected.endLine);
+						}
+
+						if (expected.endColumn !== undefined) {
+							// @ts-expect-error -- TODO: `warning.endColumn` is not implemented. See stylelint/stylelint#5725
+							expect(warning.endColumn).toBe(expected.endColumn);
+						}
 					});
 
 					if (!schema.fix) return;
@@ -157,13 +142,24 @@ function getTestRule(options = {}) {
 				}
 
 				return {
+					message: () => '',
 					pass: true,
 				};
 			},
 		});
 	};
-}
+};
 
+/**
+ * @template {TestCase} T
+ * @param {{
+ *   name: string,
+ *   cases: T[] | undefined,
+ *   schema: TestSchema,
+ *   comparisons: (testCase: T) => jest.ProvidesCallback,
+ * }} args
+ * @returns {void}
+ */
 function setupTestCases({ name, cases, schema, comparisons }) {
 	if (cases && cases.length) {
 		const testGroup = schema.only ? describe.only : schema.skip ? describe.skip : describe;
@@ -184,11 +180,16 @@ function setupTestCases({ name, cases, schema, comparisons }) {
 	}
 }
 
+/**
+ * @param {import('stylelint').LinterResult} output
+ * @returns {string}
+ */
 function getOutputCss(output) {
 	const result = output.results[0]._postcssResult;
-	const css = result.root.toString(result.opts.syntax);
 
-	return css;
-}
+	if (result && result.root && result.opts) {
+		return result.root.toString(result.opts.syntax);
+	}
 
-module.exports = getTestRule;
+	throw new TypeError('Invalid result');
+}

package/index.d.ts

@@ -0,0 +1,161 @@
+export type TestCase = {
+	/**
+	 * The code of the test case.
+	 */
+	code: string;
+
+	/**
+	 * Description of the test case.
+	 */
+	description?: string;
+
+	/**
+	 * Maps to Jest's `test.only`. Default: `false`.
+	 *
+	 * @see https://jestjs.io/docs/en/api#testonlyname-fn-timeout
+	 */
+	only?: boolean;
+
+	/**
+	 * Maps to Jest's `test.skip`. Default: `false`.
+	 *
+	 * @see https://jestjs.io/docs/api#testskipname-fn
+	 */
+	skip?: boolean;
+};
+
+export type AcceptTestCase = TestCase;
+
+export type Warning = {
+	/**
+	 * Expected message from the test case. Usually exported from the plugin.
+	 * Optional if `warnings` is used.
+	 */
+	message?: string;
+
+	/**
+	 * Expected line number of the warning.
+	 */
+	line?: number;
+
+	/**
+	 * Expected column number of the warning.
+	 */
+	column?: number;
+
+	/**
+	 * Expected end line number of the warning.
+	 */
+	endLine?: number;
+
+	/**
+	 * Expected end column number of the warning.
+	 */
+	endColumn?: number;
+};
+
+/**
+ * Use the `warnings` property, rather than `message`, `line`, and `column`,
+ * if the test case is expected to produce more than one warning.
+ */
+export type RejectTestCase = TestCase &
+	Warning & {
+		/**
+		 * Expected fixed code of the test case. Optional if `fix` isn't `true`.
+		 */
+		fixed?: string;
+
+		/**
+		 * Don't check the `fixed` code. Default: `false`.
+		 */
+		unfixable?: boolean;
+
+		/**
+		 * Warning objects containing expected `message`, `line` and `column` etc.
+		 * Optional if `message` is used.
+		 */
+		warnings?: Warning[];
+	};
+
+export type TestSchema = {
+	/**
+	 * Name of the rule being tested. Usually exported from the plugin.
+	 */
+	ruleName: string;
+
+	/**
+	 * Config to pass to the rule.
+	 */
+	config: unknown[];
+
+	/**
+	 * Accept test cases.
+	 */
+	accept?: AcceptTestCase[];
+
+	/**
+	 * Reject test cases.
+	 */
+	reject?: RejectTestCase[];
+
+	/**
+	 * Turn on autofix. Default: `false`.
+	 */
+	fix?: boolean;
+
+	/**
+	 * Maps to Stylelint's `plugins` configuration property.
+	 *
+	 * Path to the file that exports the plugin object, relative to the root.
+	 * Usually it's the same path as a `main` property in plugin's `package.json`.
+	 *
+	 * If you're testing a plugin pack, it's the path to the file that exports the array of plugin objects.
+	 *
+	 * Optional, if `plugins` option was passed to advanced configuration with `getTestRule()`.
+	 *
+	 * @see https://stylelint.io/user-guide/configure#plugins
+	 */
+	plugins?: string | string[];
+
+	/**
+	 * Maps to Stylelint's `customSyntax` option.
+	 *
+	 * @see https://stylelint.io/user-guide/usage/options#customsyntax
+	 */
+	customSyntax?: string;
+
+	/**
+	 * Maps to Stylelint's `codeFilename` option.
+	 *
+	 * @see https://stylelint.io/user-guide/usage/options#codefilename
+	 */
+	codeFilename?: string;
+
+	/**
+	 * Maps to Jest's `test.only`. Default: `false`.
+	 *
+	 * @see https://jestjs.io/docs/en/api#testonlyname-fn-timeout
+	 */
+	only?: boolean;
+
+	/**
+	 * Maps to Jest's `test.skip`. Default: `false`.
+	 *
+	 * @see https://jestjs.io/docs/api#testskipname-fn
+	 */
+	skip?: boolean;
+};
+
+/**
+ * Test a rule with the specified schema.
+ */
+export declare function testRule(schema: TestSchema): void;
+
+/**
+ * Create a `testRule()` function with any specified plugins.
+ */
+export function getTestRule(options?: { plugins?: TestSchema['plugins'] }): typeof testRule;
+
+declare global {
+	var testRule: typeof testRule;
+}

package/index.js

@@ -0,0 +1,5 @@
+'use strict';
+
+const getTestRule = require('./getTestRule');
+
+module.exports = { getTestRule };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jest-preset-stylelint",
-  "version": "4.2.0",
+  "version": "5.0.0",
   "description": "Jest preset for Stylelint plugins.",
   "keywords": [
     "stylelint",
@@ -11,17 +11,21 @@
   "repository": "stylelint/jest-preset-stylelint",
   "license": "MIT",
   "author": "stylelint",
+  "main": "index.js",
+  "types": "index.d.ts",
   "files": [
     "getTestRule.js",
     "jest-preset.js",
-    "jest-setup.js"
+    "jest-setup.js",
+    "index.d.ts"
   ],
   "scripts": {
     "format": "prettier . --write",
     "lint": "npm-run-all --parallel lint:*",
     "lint:formatting": "prettier . --check",
-    "lint:js": "eslint . ",
-    "lint:md": "remark . --quiet --frail ",
+    "lint:js": "eslint .",
+    "lint:md": "remark . --quiet --frail",
+    "lint:types": "tsc",
     "release": "np",
     "test": "jest",
     "watch": "jest --watch",
@@ -39,7 +43,9 @@
     "globals": {
       "module": true,
       "require": true
-    }
+    },
+    "reportUnusedDisableDirectives": true,
+    "root": true
   },
   "remarkConfig": {
     "plugins": [
@@ -49,16 +55,18 @@
   "devDependencies": {
     "@stylelint/prettier-config": "^2.0.0",
     "@stylelint/remark-preset": "^3.0.0",
-    "eslint": "^8.2.0",
+    "@types/jest": "^27.4.0",
+    "eslint": "^8.9.0",
     "eslint-config-stylelint": "^15.0.0",
     "husky": "^7.0.4",
-    "jest": "^27.3.1",
-    "lint-staged": "^11.2.6",
-    "np": "^7.5.0",
+    "jest": "^27.5.1",
+    "lint-staged": "^12.3.4",
+    "np": "^7.6.0",
     "npm-run-all": "^4.1.5",
-    "prettier": "^2.4.1",
-    "remark-cli": "^10.0.0",
-    "stylelint": "^14.0.1"
+    "prettier": "^2.5.1",
+    "remark-cli": "^10.0.1",
+    "stylelint": "^14.5.1",
+    "typescript": "^4.5.5"
   },
   "peerDependencies": {
     "jest": "^25.3.0 || ^26.0.1 || ^27.0.1"