@double-great/stylelint-a11y 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -5,6 +5,40 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.2.0] - 2025-08-16
+
+### Added
+
+- Comprehensive E2E testing infrastructure with real-world projects
+- Integration testing suite for plugin functionality
+- Performance benchmarking with regression detection
+- Test helper utilities for simplified testing
+- Support for SCSS/Sass project testing
+- Large codebase performance testing
+- CLI integration tests with full stylelint compatibility
+- Development documentation in README
+- Pull request template for consistent PR descriptions
+
+### Changed
+
+- Standardized import patterns across all rules for better consistency
+- Fixed rule order in exports object to maintain alphabetical sorting
+- Improved Jest configuration for multiple test types
+- Enhanced ESLint configuration for E2E tests
+- Updated actions/checkout from v4 to v5 (#77)
+
+### Fixed
+
+- Fixed `media-prefers-reduced-motion` rule incorrectly adding duplicate media queries when `prefers-reduced-motion` is already nested inside another media query (#66)
+
+### Developer Experience
+
+- Added npm scripts for granular test execution (`test:unit`, `test:integration`, `test:e2e`, `test:all`)
+- Simplified test utilities for faster development
+- Cross-platform compatibility testing
+- Performance metrics and scaling tests
+- Individual rule benchmarks included
+
 ## [3.1.0] - 2025-08-16
 
 ### Added

package/README.md

@@ -52,19 +52,31 @@ This shareable config contains the following:
 
 Since it adds stylelint-a11y to `plugins`, you don't have to do this yourself when extending this config.
 
-## Help out
+## Development
 
-There work on the plugin's rules is still in progress, so if you feel like it, you're welcome to help out in any of these (the plugin follows stylelint guidelines so most part of this is based on its docs):
+### Testing
 
-- Create, enhance, and debug rules (see stylelint's guide to "[Working on rules](https://github.com/stylelint/stylelint/blob/main/docs/developer-guide/rules.md)").
-- Improve documentation.
-- Chime in on any open issue or pull request.
-- Open new issues about your ideas on new rules, or for how to improve the existing ones, and pull requests to show us how your idea works.
-- Add new tests to absolutely anything.
-- Work on improving performance of rules.
-- Contribute to [stylelint](https://github.com/stylelint/stylelint)
-- Spread the word.
+Run tests with the following commands:
 
-We communicate via [issues](https://github.com/double-great/stylelint-a11y/issues) and [pull requests](https://github.com/double-great/stylelint-a11y/pulls).
+- `npm run test` - Run unit tests for all rules
+- `npm run test:unit` - Run unit tests only
+- `npm run test:integration` - Run integration tests
+- `npm run test:e2e` - Run end-to-end tests with real projects
+- `npm run test:performance` - Run performance benchmarks
+- `npm run test:all` - Run complete test suite
 
-There is also [stackoverflow](https://stackoverflow.com/questions/tagged/stylelint), which would be the preferred QA forum.
+### Testing Infrastructure
+
+This project includes testing at a few levels:
+
+- **Unit tests** - Individual rule functionality
+- **Integration tests** - Plugin integration with stylelint
+- **E2E tests** - Real-world project testing with intentional violations
+- **Performance tests** - Benchmark testing for large codebases
+
+### Other Commands
+
+- `npm run lint` - Run ESLint
+- `npm run format:check` - Check code formatting
+- `npm run format:fix` - Fix code formatting
+- `npm run coverage` - Run tests with coverage report

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@double-great/stylelint-a11y",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Plugin for stylelint with a11y rules",
   "main": "src/index.js",
   "type": "module",
@@ -28,8 +28,14 @@
     "pretest": "npm run lint && npm run format:check",
     "format:check": "prettier --check .",
     "format:fix": "prettier --write .",
-    "test": "jest",
-    "coverage": "jest --coverage"
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:unit": "node --experimental-vm-modules node_modules/jest/bin/jest.js src",
+    "test:integration": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/integration",
+    "test:e2e": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/e2e",
+    "test:performance": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/e2e/performance.test.js",
+    "test:all": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
+    "coverage:all": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage"
   },
   "prettier": {
     "printWidth": 100,
@@ -48,6 +54,7 @@
     "jest": "^30.0.5",
     "jest-light-runner": "^0.7.9",
     "jest-preset-stylelint": "^8.0.0",
+    "postcss-scss": "^4.0.9",
     "prettier": "^3.6.2",
     "stylelint": "^16.23.1"
   },

package/src/rules/index.js

@@ -15,6 +15,7 @@ export default {
   'content-property-no-static-value': contentPropertyNoStaticValue,
   'font-size-is-readable': fontSizeIsReadable,
   'line-height-is-vertical-rhythmed': lineHeightIsVerticalRhythmed,
+  'media-prefers-color-scheme': mediaPrefersColorScheme,
   'media-prefers-reduced-motion': mediaPrefersReducedMotion,
   'no-display-none': noDisplayNone,
   'no-obsolete-attribute': noObsoleteAttribute,
@@ -23,5 +24,4 @@ export default {
   'no-spread-text': noSpreadText,
   'no-text-align-justify': noTextAlignJustify,
   'selector-pseudo-class-focus': selectorPseudoClassFocus,
-  'media-prefers-color-scheme': mediaPrefersColorScheme,
 };

package/src/rules/media-prefers-reduced-motion/index.js

@@ -2,7 +2,9 @@ import isCustomSelector from 'stylelint/lib/utils/isCustomSelector.mjs';
 import isStandardSyntaxAtRule from 'stylelint/lib/utils/isStandardSyntaxAtRule.mjs';
 import isStandardSyntaxRule from 'stylelint/lib/utils/isStandardSyntaxRule.mjs';
 import isStandardSyntaxSelector from 'stylelint/lib/utils/isStandardSyntaxSelector.mjs';
+
 import { parse } from 'postcss';
+
 import stylelint from 'stylelint';
 const {
   utils: { report, ruleMessages, validateOptions },
@@ -62,6 +64,30 @@ function check(selector, node) {
 
   if (!declarationsIsMatched) return true;
 
+  // Check if there's a nested media query with prefers-reduced-motion inside the current rule
+  const hasNestedPrefersReducedMotion = declarations.some((childNode) => {
+    if (childNode.type === 'atrule' && childNode.name === 'media') {
+      return childNode.params && childNode.params.indexOf('prefers-reduced-motion') >= 0;
+    }
+
+    return false;
+  });
+
+  if (hasNestedPrefersReducedMotion) return true;
+
+  // Check if there's a sibling media query with prefers-reduced-motion at the same level
+  if (node.parent && node.parent.type === 'atrule' && node.parent.name === 'media') {
+    const siblingHasPrefersReducedMotion = node.parent.nodes.some((siblingNode) => {
+      if (siblingNode.type === 'atrule' && siblingNode.name === 'media') {
+        return siblingNode.params && siblingNode.params.indexOf('prefers-reduced-motion') >= 0;
+      }
+
+      return false;
+    });
+
+    if (siblingHasPrefersReducedMotion) return true;
+  }
+
   if (declarationsIsMatched) {
     const parentMatchedNode = parentNodes.some((parentNode) => {
       if (!parentNode || !parentNode.nodes) return false;
@@ -143,25 +169,62 @@ export default function mediaPrefersReducedMotion(actual, _, context) {
         media.nodes.forEach((o) => {
           o.raws.after = '\n';
         });
-        const cloneRule = node.clone();
-
-        cloneRule.raws = {
-          ...cloneRule.raws,
-          before: '\n',
-          after: '\n',
-          semicolon: true,
-        };
-        cloneRule.nodes.forEach((o) => {
-          if (o.prop === 'animation-name') {
-            o.prop = 'animation';
-          }
-
-          if (targetProperties.indexOf(o.prop) >= 0) {
-            o.value = 'none';
-          }
-        });
-        media.first.append(cloneRule);
-        node.before(media);
+
+        // Check if we're already inside a media query
+        if (node.parent && node.parent.type === 'atrule' && node.parent.name === 'media') {
+          // Create a clone with only the animation/transition properties set to none
+          const cloneRule = node.clone();
+
+          cloneRule.nodes = cloneRule.nodes.filter((o) => {
+            if (o.prop === 'animation-name') {
+              o.prop = 'animation';
+              o.value = 'none';
+
+              return true;
+            }
+
+            if (targetProperties.indexOf(o.prop) >= 0) {
+              o.value = 'none';
+
+              return true;
+            }
+
+            return false;
+          });
+
+          cloneRule.raws = {
+            ...cloneRule.raws,
+            before: '\n',
+            after: '\n',
+            semicolon: true,
+          };
+
+          media.first.append(cloneRule);
+          // Insert the nested media query inside the current rule
+          node.append(media.first);
+        } else {
+          // Original logic for non-nested case
+          const cloneRule = node.clone();
+
+          cloneRule.raws = {
+            ...cloneRule.raws,
+            before: '\n',
+            after: '\n',
+            semicolon: true,
+          };
+          cloneRule.nodes.forEach((o) => {
+            if (o.prop === 'animation-name') {
+              o.prop = 'animation';
+            }
+
+            if (targetProperties.indexOf(o.prop) >= 0) {
+              o.value = 'none';
+            }
+          });
+          media.first.append(cloneRule);
+          // Insert the media query before the current node
+          node.before(media);
+        }
 
         return;
       }

package/src/rules/no-obsolete-attribute/index.js

@@ -1,5 +1,7 @@
 import isStandardSyntaxRule from 'stylelint/lib/utils/isStandardSyntaxRule.mjs';
+
 import { obsoleteAttributes } from './obsoleteAttributes.js';
+
 import stylelint from 'stylelint';
 const {
   utils: { report, ruleMessages, validateOptions },

package/src/rules/no-obsolete-element/index.js

@@ -1,5 +1,7 @@
 import isStandardSyntaxRule from 'stylelint/lib/utils/isStandardSyntaxRule.mjs';
+
 import { obsoleteElements } from './obsoleteElements.js';
+
 import stylelint from 'stylelint';
 const {
   utils: { report, ruleMessages, validateOptions },

package/test/e2e/README.md

@@ -0,0 +1,37 @@
+# E2E Test Information
+
+## About E2E Test "Failures"
+
+The E2E tests in this directory are designed to test stylelint-a11y against real CSS files that **intentionally contain rule violations**.
+
+### Expected Behavior
+
+- Tests **expect** stylelint to exit with error codes when violations are found
+- The tests catch these "failures" and parse the JSON output to verify:
+  - Correct number of violations detected
+  - Specific rules are triggered
+  - Line numbers and error messages are accurate
+
+### Test Output
+
+The console output may show:
+
+- JSON arrays of violations (this is expected)
+- Some error messages during test runs (also expected)
+- Performance metrics from the performance tests
+
+### In CI/GitHub Actions
+
+These tests will pass in CI because:
+
+- Jest catches the expected exceptions
+- Tests verify the violations are correctly detected
+- The test suite itself passes even though stylelint "fails" on the test CSS
+
+## Test Projects
+
+- `basic-css/`: Tests core CSS functionality
+- `scss-project/`: Tests SCSS/Sass compatibility
+- `large-codebase/`: Tests performance with larger files
+
+All test projects contain intentional accessibility violations for testing purposes.

package/test/e2e/cli.test.js

@@ -0,0 +1,71 @@
+import { execSync } from 'child_process';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import fs from 'fs/promises';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+describe('CLI Integration Tests', () => {
+  const projectRoot = join(__dirname, '../..');
+
+  it('should work with recommended config via CLI', async () => {
+    // Create a minimal test to verify CLI works with the plugin
+    const testCssFile = join(projectRoot, 'test-cli-temp.css');
+    const testConfigFile = join(projectRoot, '.stylelintrc-cli-temp.json');
+
+    try {
+      await fs.writeFile(testCssFile, '.test:focus { outline: none; }');
+      await fs.writeFile(
+        testConfigFile,
+        JSON.stringify({
+          plugins: ['./src/index.js'],
+          rules: { 'a11y/no-outline-none': true },
+        })
+      );
+
+      try {
+        execSync(`npx stylelint "${testCssFile}" --config "${testConfigFile}"`, {
+          cwd: projectRoot,
+          encoding: 'utf8',
+        });
+
+        throw new Error('Expected stylelint to exit with non-zero code');
+      } catch (error) {
+        expect(error.status).toBeGreaterThan(0);
+      }
+    } finally {
+      // Cleanup
+      await fs.unlink(testCssFile).catch(() => {});
+      await fs.unlink(testConfigFile).catch(() => {});
+    }
+  });
+
+  it('should handle valid CSS without CLI errors', async () => {
+    const testCssFile = join(projectRoot, 'test-cli-valid-temp.css');
+    const testConfigFile = join(projectRoot, '.stylelintrc-valid-temp.json');
+
+    try {
+      await fs.writeFile(testCssFile, '.test:hover:focus { color: blue; }');
+      await fs.writeFile(
+        testConfigFile,
+        JSON.stringify({
+          plugins: ['./src/index.js'],
+          rules: { 'a11y/selector-pseudo-class-focus': true },
+        })
+      );
+
+      const result = execSync(`npx stylelint "${testCssFile}" --config "${testConfigFile}"`, {
+        cwd: projectRoot,
+        encoding: 'utf8',
+      });
+
+      // Should succeed without errors
+      expect(typeof result).toBe('string');
+    } finally {
+      // Cleanup
+      await fs.unlink(testCssFile).catch(() => {});
+      await fs.unlink(testConfigFile).catch(() => {});
+    }
+  });
+});

package/test/e2e/performance.test.js

@@ -0,0 +1,98 @@
+import { testCSS, getWarnings } from '../helpers/simple-test-utils.js';
+
+describe('Performance Tests', () => {
+  it('should process rules efficiently', async () => {
+    const testCss = `
+      .test1:focus { outline: none; }
+      .test2:hover { color: blue; }
+      .test3 { font-size: 10px; }
+      .test4::before { content: "text"; }
+      .test5 { line-height: 1.0; }
+      .test6 { text-align: justify; }
+      .test7 { animation: slide 1s; }
+      .test8 { display: none; }
+    `.repeat(50); // Create larger test case
+
+    const times = [];
+
+    // Run multiple iterations to get average performance
+    for (let i = 0; i < 3; i++) {
+      const startTime = process.hrtime.bigint();
+
+      await testCSS(testCss, {
+        'no-outline-none': true,
+        'selector-pseudo-class-focus': true,
+        'font-size-is-readable': true,
+        'content-property-no-static-value': true,
+        'line-height-is-vertical-rhythmed': true,
+        'no-text-align-justify': true,
+        'media-prefers-reduced-motion': true,
+        'no-display-none': true,
+      });
+
+      const endTime = process.hrtime.bigint();
+      const duration = Number(endTime - startTime) / 1000000; // Convert to milliseconds
+
+      times.push(duration);
+    }
+
+    const averageTime = times.reduce((sum, time) => sum + time, 0) / times.length;
+
+    // Performance assertions
+    expect(averageTime).toBeLessThan(1000); // Average should be under 1 second
+  });
+
+  it('should scale reasonably with CSS size', async () => {
+    const baseCss = '.test:focus { outline: none; } .test:hover { color: blue; }';
+    const sizes = [100, 500]; // Different repetition counts
+    const results = [];
+
+    for (const size of sizes) {
+      const testCss = baseCss.repeat(size);
+
+      const startTime = process.hrtime.bigint();
+
+      await testCSS(testCss, {
+        'no-outline-none': true,
+        'selector-pseudo-class-focus': true,
+      });
+
+      const endTime = process.hrtime.bigint();
+      const duration = Number(endTime - startTime) / 1000000;
+
+      results.push({ size, duration });
+    }
+
+    // Check that performance scales reasonably
+    const scalingFactor = results[1].duration / results[0].duration; // 500 vs 100 rules
+
+    expect(scalingFactor).toBeLessThan(25); // Should not be more than 25x slower for 5x content
+  });
+
+  it('should handle large stylesheets without memory issues', async () => {
+    let largeCss = '';
+
+    for (let i = 0; i < 100; i++) {
+      largeCss += `.component-${i} { font-size: 10px; color: red; }\n`;
+      largeCss += `.component-${i}:hover { color: blue; }\n`;
+      largeCss += `.component-${i}:focus { outline: none; }\n`;
+    }
+
+    const memoryBefore = process.memoryUsage().heapUsed;
+
+    const warnings = await getWarnings(largeCss, {
+      'no-outline-none': true,
+      'font-size-is-readable': true,
+      'selector-pseudo-class-focus': true,
+    });
+
+    const memoryAfter = process.memoryUsage().heapUsed;
+    const memoryDiff = memoryAfter - memoryBefore;
+
+    // Should detect violations
+    expect(warnings.length).toBeGreaterThan(0);
+
+    // Memory usage should be reasonable (less than 50MB increase)
+    expect(memoryDiff).toBeLessThan(50 * 1024 * 1024);
+  });
+});

package/test/e2e/projects/basic-css/.stylelintrc.json

@@ -0,0 +1,17 @@
+{
+  "plugins": ["../../../../src/index.js"],
+  "rules": {
+    "a11y/content-property-no-static-value": true,
+    "a11y/font-size-is-readable": true,
+    "a11y/line-height-is-vertical-rhythmed": true,
+    "a11y/media-prefers-color-scheme": true,
+    "a11y/media-prefers-reduced-motion": true,
+    "a11y/no-display-none": true,
+    "a11y/no-obsolete-attribute": true,
+    "a11y/no-obsolete-element": true,
+    "a11y/no-outline-none": true,
+    "a11y/no-spread-text": true,
+    "a11y/no-text-align-justify": true,
+    "a11y/selector-pseudo-class-focus": true
+  }
+}

package/test/e2e/projects/basic-css/styles.css

@@ -0,0 +1,81 @@
+/* Basic CSS project for E2E testing */
+
+/* Navigation styles */
+.nav {
+  background: #333;
+  padding: 1rem;
+}
+
+.nav a:hover {
+  color: #fff;
+  text-decoration: none;
+}
+
+.nav .active {
+  font-weight: bold;
+}
+
+/* Button styles */
+.btn:focus {
+  outline: none; /* Should trigger a11y/no-outline-none */
+  background: #007bff;
+}
+
+.btn-primary {
+  background: #007bff;
+  color: white;
+  padding: 0.5rem 1rem;
+  border: none;
+  font-size: 12px; /* Should trigger a11y/font-size-is-readable */
+}
+
+.btn-secondary:hover {
+  background: #6c757d; /* Should trigger a11y/selector-pseudo-class-focus */
+}
+
+/* Content styles */
+.content::before {
+  content: '★'; /* Should trigger a11y/content-property-no-static-value */
+  color: gold;
+}
+
+.article {
+  line-height: 1.2; /* Should trigger a11y/line-height-is-vertical-rhythmed */
+  text-align: justify; /* Should trigger a11y/no-text-align-justify */
+}
+
+/* Animations */
+.slide-in {
+  animation: slideIn 0.5s ease; /* Should trigger a11y/media-prefers-reduced-motion */
+}
+
+@keyframes slideIn {
+  from {
+    transform: translateX(-100%);
+  }
+  to {
+    transform: translateX(0);
+  }
+}
+
+/* Hidden elements */
+.sr-only {
+  display: none; /* Should trigger a11y/no-display-none */
+}
+
+/* Obsolete elements and attributes */
+center {
+  margin: 0 auto; /* Should trigger a11y/no-obsolete-element */
+}
+
+.old-style {
+  text-decoration: blink; /* Should trigger a11y/no-obsolete-attribute */
+}
+
+/* Media queries */
+@media screen and (max-width: 768px) {
+  .mobile-nav a:hover {
+    color: blue; /* Should trigger a11y/selector-pseudo-class-focus */
+    font-size: 10px; /* Should trigger a11y/font-size-is-readable */
+  }
+}

package/test/e2e/projects/large-codebase/.stylelintrc.json

@@ -0,0 +1,17 @@
+{
+  "plugins": ["../../../../src/index.js"],
+  "rules": {
+    "a11y/content-property-no-static-value": true,
+    "a11y/font-size-is-readable": [true, { "minSize": 12 }],
+    "a11y/line-height-is-vertical-rhythmed": true,
+    "a11y/media-prefers-color-scheme": true,
+    "a11y/media-prefers-reduced-motion": true,
+    "a11y/no-display-none": true,
+    "a11y/no-obsolete-attribute": true,
+    "a11y/no-obsolete-element": true,
+    "a11y/no-outline-none": true,
+    "a11y/no-spread-text": true,
+    "a11y/no-text-align-justify": true,
+    "a11y/selector-pseudo-class-focus": true
+  }
+}