jest-preset-stylelint 4.1.0 → 5.0.0

package/README.md

@@ -2,11 +2,11 @@
 
 [![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
 
-Install the preset alongside jest and stylelint:
+Install the preset alongside Jest and Stylelint:
 
 ```bash
 npm install jest-preset-stylelint jest stylelint --save-dev
@@ -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,113 +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).
-
-## 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

@@ -1,34 +1,16 @@
 'use strict';
 
 const util = require('util');
-const { basicChecks, lint } = require('stylelint');
+// eslint-disable-next-line node/no-unpublished-require -- Avoid auto-install of `stylelint` peer dependency.
+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 {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 = {
@@ -38,21 +20,16 @@ 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 = {
 						code: testCase.code,
 						config: stylelintConfig,
 						customSyntax: schema.customSyntax,
+						codeFilename: schema.codeFilename,
 					};
 
 					const output = await lint(stylelintOptions);
@@ -79,6 +56,7 @@ function getTestRule(options = {}) {
 						code: testCase.code,
 						config: stylelintConfig,
 						customSyntax: schema.customSyntax,
+						codeFilename: schema.codeFilename,
 					};
 
 					const outputAfterLint = await lint(stylelintOptions);
@@ -91,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);
@@ -102,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;
@@ -153,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;
@@ -180,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,7 +1,7 @@
 {
   "name": "jest-preset-stylelint",
-  "version": "4.1.0",
-  "description": "Jest preset for stylelint plugins.",
+  "version": "5.0.0",
+  "description": "Jest preset for Stylelint plugins.",
   "keywords": [
     "stylelint",
     "jest",
@@ -11,25 +11,25 @@
   "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"
-  },
-  "husky": {
-    "hooks": {
-      "pre-commit": "lint-staged"
-    }
+    "watch": "jest --watch",
+    "prepare": "husky install"
   },
   "lint-staged": {
     "*.js": "eslint --cache --fix",
@@ -39,7 +39,13 @@
   "eslintConfig": {
     "extends": [
       "stylelint"
-    ]
+    ],
+    "globals": {
+      "module": true,
+      "require": true
+    },
+    "reportUnusedDisableDirectives": true,
+    "root": true
   },
   "remarkConfig": {
     "plugins": [
@@ -48,20 +54,22 @@
   },
   "devDependencies": {
     "@stylelint/prettier-config": "^2.0.0",
-    "@stylelint/remark-preset": "^2.0.0",
-    "eslint": "^7.26.0",
-    "eslint-config-stylelint": "^13.1.0",
-    "husky": "^6.0.0",
-    "jest": "^26.0.1",
-    "lint-staged": "^11.0.0",
-    "np": "^7.5.0",
+    "@stylelint/remark-preset": "^3.0.0",
+    "@types/jest": "^27.4.0",
+    "eslint": "^8.9.0",
+    "eslint-config-stylelint": "^15.0.0",
+    "husky": "^7.0.4",
+    "jest": "^27.5.1",
+    "lint-staged": "^12.3.4",
+    "np": "^7.6.0",
     "npm-run-all": "^4.1.5",
-    "prettier": "^2.3.0",
-    "remark-cli": "^9.0.0",
-    "stylelint": "^13.3.2"
+    "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"
+    "jest": "^25.3.0 || ^26.0.1 || ^27.0.1"
   },
   "engines": {
     "node": "^12.20.0 || ^14.13.1 || >=16.0.0"