test-a11y-js 0.1.0

package/LICENSE

@@ -0,0 +1,45 @@
+MIT License
+
+Copyright (c) 2024 Marlon Maniti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## API Reference
+
+### A11yChecker
+
+#### `check(element: Element): Promise<A11yResults>`
+Performs all accessibility checks on the given element.
+
+#### `checkImageAlt(element: Element): A11yViolation[]`
+Checks images for proper alt attributes.
+
+#### `checkLinkText(element: Element): A11yViolation[]`
+Validates link text for accessibility.
+
+#### `checkButtonLabel(element: Element): A11yViolation[]`
+Ensures buttons have proper labels.
+
+#### `checkFormLabels(element: Element): A11yViolation[]`
+Validates form control label associations.
+
+#### `checkHeadingOrder(element: Element): A11yViolation[]`
+Checks heading hierarchy.
+
+### Types

package/README.md

@@ -0,0 +1,76 @@
+# test-a11y-js
+
+A JavaScript library for testing component accessibility across multiple testing frameworks.
+
+## Installation
+
+```bash
+npm install test-a11y-js
+```
+
+## Usage
+
+```typescript
+import { A11yChecker } from 'test-a11y-js'
+// Test a DOM element for accessibility violations
+const results = await A11yChecker.check(element)
+// Individual checks
+const imageViolations = A11yChecker.checkImageAlt(element)
+const linkViolations = A11yChecker.checkLinkText(element)
+const buttonViolations = A11yChecker.checkButtonLabel(element)
+const formViolations = A11yChecker.checkFormLabels(element)
+    const headingViolations = A11yChecker.checkHeadingOrder(element)
+```
+
+## API
+
+### A11yChecker
+
+#### `check(element: Element): Promise<A11yResults>`
+Performs all accessibility checks on the given element.
+
+#### `checkImageAlt(element: Element): A11yViolation[]`
+Checks images for proper alt attributes.
+
+#### `checkLinkText(element: Element): A11yViolation[]`
+Validates link text for accessibility.
+
+#### `checkButtonLabel(element: Element): A11yViolation[]`
+Ensures buttons have proper labels.
+
+#### `checkFormLabels(element: Element): A11yViolation[]`
+Validates form control label associations.
+
+#### `checkHeadingOrder(element: Element): A11yViolation[]`
+Checks heading hierarchy.
+
+### Types
+
+```typescript
+interface A11yViolation {
+  id: string
+  description: string
+  element: Element
+  impact: 'critical' | 'serious' | 'moderate' | 'minor'
+}
+
+interface A11yResults {
+  violations: A11yViolation[]
+}
+```
+
+## Features
+
+- Image alt text validation
+- Link text accessibility checks
+- Button label validation
+- Form label association checks
+- Heading order validation
+
+## Author
+
+Marlon Maniti (https://github.com/nolrm)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,19 @@
+interface A11yViolation {
+    id: string;
+    description: string;
+    element: Element;
+    impact: 'critical' | 'serious' | 'moderate' | 'minor';
+}
+interface A11yResults {
+    violations: A11yViolation[];
+}
+declare class A11yChecker {
+    static checkImageAlt(element: Element): A11yViolation[];
+    static checkButtonLabel(element: Element): A11yViolation[];
+    static checkFormLabels(element: Element): A11yViolation[];
+    static checkHeadingOrder(element: Element): A11yViolation[];
+    static checkLinkText(element: Element): A11yViolation[];
+    static check(element: Element): Promise<A11yResults>;
+}
+
+export { A11yChecker, A11yResults, A11yViolation };

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+interface A11yViolation {
+    id: string;
+    description: string;
+    element: Element;
+    impact: 'critical' | 'serious' | 'moderate' | 'minor';
+}
+interface A11yResults {
+    violations: A11yViolation[];
+}
+declare class A11yChecker {
+    static checkImageAlt(element: Element): A11yViolation[];
+    static checkButtonLabel(element: Element): A11yViolation[];
+    static checkFormLabels(element: Element): A11yViolation[];
+    static checkHeadingOrder(element: Element): A11yViolation[];
+    static checkLinkText(element: Element): A11yViolation[];
+    static check(element: Element): Promise<A11yResults>;
+}
+
+export { A11yChecker, A11yResults, A11yViolation };

package/dist/index.js

@@ -0,0 +1,150 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  A11yChecker: () => A11yChecker
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/core/a11y-checker.ts
+var A11yChecker = class {
+  static checkImageAlt(element) {
+    const violations = [];
+    const images = element.getElementsByTagName("img");
+    for (const img of Array.from(images)) {
+      if (!img.hasAttribute("alt")) {
+        violations.push({
+          id: "image-alt",
+          description: "Image must have an alt attribute",
+          element: img,
+          impact: "serious"
+        });
+      } else if (img.getAttribute("alt")?.trim() === "") {
+        violations.push({
+          id: "image-alt",
+          description: "Image alt attribute must not be empty",
+          element: img,
+          impact: "serious"
+        });
+      }
+    }
+    return violations;
+  }
+  static checkButtonLabel(element) {
+    const violations = [];
+    const buttons = element.getElementsByTagName("button");
+    for (const button of Array.from(buttons)) {
+      if (!button.textContent?.trim() && !button.getAttribute("aria-label")) {
+        violations.push({
+          id: "button-label",
+          description: "Button must have a label or aria-label",
+          element: button,
+          impact: "critical"
+        });
+      }
+    }
+    return violations;
+  }
+  static checkFormLabels(element) {
+    const violations = [];
+    const inputs = element.querySelectorAll("input, select, textarea");
+    for (const input of Array.from(inputs)) {
+      const hasLabel = input.hasAttribute("id") && element.querySelector(`label[for="${input.getAttribute("id")}"]`);
+      const hasAriaLabel = input.hasAttribute("aria-label");
+      const hasAriaLabelledBy = input.hasAttribute("aria-labelledby") && document.getElementById(input.getAttribute("aria-labelledby") || "");
+      if (!hasLabel && !hasAriaLabel && !hasAriaLabelledBy) {
+        violations.push({
+          id: "form-label",
+          description: "Form control must have an associated label",
+          element: input,
+          impact: "critical"
+        });
+      }
+    }
+    return violations;
+  }
+  static checkHeadingOrder(element) {
+    const violations = [];
+    const headings = element.querySelectorAll("h1, h2, h3, h4, h5, h6");
+    let previousLevel = 0;
+    for (const heading of Array.from(headings)) {
+      const currentLevel = parseInt(heading.tagName[1]);
+      if (previousLevel > 0 && currentLevel - previousLevel > 1) {
+        violations.push({
+          id: "heading-order",
+          description: `Heading level skipped from h${previousLevel} to h${currentLevel}`,
+          element: heading,
+          impact: "moderate"
+        });
+      }
+      previousLevel = currentLevel;
+    }
+    return violations;
+  }
+  static checkLinkText(element) {
+    const violations = [];
+    const links = element.getElementsByTagName("a");
+    for (const link of Array.from(links)) {
+      const text = link.textContent?.trim().toLowerCase() || "";
+      const ariaLabel = link.getAttribute("aria-label")?.toLowerCase();
+      if (!text && !ariaLabel) {
+        violations.push({
+          id: "link-text",
+          description: "Link must have descriptive text",
+          element: link,
+          impact: "serious"
+        });
+      } else if (["click here", "read more", "more"].includes(text) && !ariaLabel) {
+        violations.push({
+          id: "link-text-descriptive",
+          description: "Link text should be more descriptive",
+          element: link,
+          impact: "moderate"
+        });
+      }
+    }
+    return violations;
+  }
+  static async check(element) {
+    const violations = [
+      ...this.checkImageAlt(element),
+      ...this.checkLinkText(element),
+      ...this.checkButtonLabel(element),
+      ...this.checkFormLabels(element),
+      ...this.checkHeadingOrder(element)
+    ];
+    if (violations.length > 0) {
+      console.warn("\nAccessibility Violations Found:");
+      violations.forEach((violation, index) => {
+        console.warn(`
+${index + 1}. ${violation.id} (${violation.impact})`);
+        console.warn(`   Description: ${violation.description}`);
+        console.warn(`   Element: ${violation.element.outerHTML}`);
+      });
+      console.warn("\n");
+    }
+    return { violations };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  A11yChecker
+});

package/dist/index.mjs

@@ -0,0 +1,123 @@
+// src/core/a11y-checker.ts
+var A11yChecker = class {
+  static checkImageAlt(element) {
+    const violations = [];
+    const images = element.getElementsByTagName("img");
+    for (const img of Array.from(images)) {
+      if (!img.hasAttribute("alt")) {
+        violations.push({
+          id: "image-alt",
+          description: "Image must have an alt attribute",
+          element: img,
+          impact: "serious"
+        });
+      } else if (img.getAttribute("alt")?.trim() === "") {
+        violations.push({
+          id: "image-alt",
+          description: "Image alt attribute must not be empty",
+          element: img,
+          impact: "serious"
+        });
+      }
+    }
+    return violations;
+  }
+  static checkButtonLabel(element) {
+    const violations = [];
+    const buttons = element.getElementsByTagName("button");
+    for (const button of Array.from(buttons)) {
+      if (!button.textContent?.trim() && !button.getAttribute("aria-label")) {
+        violations.push({
+          id: "button-label",
+          description: "Button must have a label or aria-label",
+          element: button,
+          impact: "critical"
+        });
+      }
+    }
+    return violations;
+  }
+  static checkFormLabels(element) {
+    const violations = [];
+    const inputs = element.querySelectorAll("input, select, textarea");
+    for (const input of Array.from(inputs)) {
+      const hasLabel = input.hasAttribute("id") && element.querySelector(`label[for="${input.getAttribute("id")}"]`);
+      const hasAriaLabel = input.hasAttribute("aria-label");
+      const hasAriaLabelledBy = input.hasAttribute("aria-labelledby") && document.getElementById(input.getAttribute("aria-labelledby") || "");
+      if (!hasLabel && !hasAriaLabel && !hasAriaLabelledBy) {
+        violations.push({
+          id: "form-label",
+          description: "Form control must have an associated label",
+          element: input,
+          impact: "critical"
+        });
+      }
+    }
+    return violations;
+  }
+  static checkHeadingOrder(element) {
+    const violations = [];
+    const headings = element.querySelectorAll("h1, h2, h3, h4, h5, h6");
+    let previousLevel = 0;
+    for (const heading of Array.from(headings)) {
+      const currentLevel = parseInt(heading.tagName[1]);
+      if (previousLevel > 0 && currentLevel - previousLevel > 1) {
+        violations.push({
+          id: "heading-order",
+          description: `Heading level skipped from h${previousLevel} to h${currentLevel}`,
+          element: heading,
+          impact: "moderate"
+        });
+      }
+      previousLevel = currentLevel;
+    }
+    return violations;
+  }
+  static checkLinkText(element) {
+    const violations = [];
+    const links = element.getElementsByTagName("a");
+    for (const link of Array.from(links)) {
+      const text = link.textContent?.trim().toLowerCase() || "";
+      const ariaLabel = link.getAttribute("aria-label")?.toLowerCase();
+      if (!text && !ariaLabel) {
+        violations.push({
+          id: "link-text",
+          description: "Link must have descriptive text",
+          element: link,
+          impact: "serious"
+        });
+      } else if (["click here", "read more", "more"].includes(text) && !ariaLabel) {
+        violations.push({
+          id: "link-text-descriptive",
+          description: "Link text should be more descriptive",
+          element: link,
+          impact: "moderate"
+        });
+      }
+    }
+    return violations;
+  }
+  static async check(element) {
+    const violations = [
+      ...this.checkImageAlt(element),
+      ...this.checkLinkText(element),
+      ...this.checkButtonLabel(element),
+      ...this.checkFormLabels(element),
+      ...this.checkHeadingOrder(element)
+    ];
+    if (violations.length > 0) {
+      console.warn("\nAccessibility Violations Found:");
+      violations.forEach((violation, index) => {
+        console.warn(`
+${index + 1}. ${violation.id} (${violation.impact})`);
+        console.warn(`   Description: ${violation.description}`);
+        console.warn(`   Element: ${violation.element.outerHTML}`);
+      });
+      console.warn("\n");
+    }
+    return { violations };
+  }
+};
+export {
+  A11yChecker
+};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "test-a11y-js",
+  "version": "0.1.0",
+  "description": "A JavaScript library for testing component accessibility across multiple testing frameworks",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/**/*.ts",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "testing",
+    "components",
+    "vitest",
+    "unit-testing",
+    "wcag"
+  ],
+  "author": "Marlon Maniti (https://github.com/nolrm)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nolrm/test-a11y-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nolrm/test-a11y-js/issues"
+  },
+  "homepage": "https://github.com/nolrm/test-a11y-js#readme",
+  "dependencies": {},
+  "peerDependencies": {
+    "vitest": ">=0.30.0"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^9.0.0",
+    "@types/node": "^18.15.0",
+    "@typescript-eslint/eslint-plugin": "^5.57.0",
+    "@typescript-eslint/parser": "^5.57.0",
+    "@vitejs/plugin-vue": "^4.0.0",
+    "@vitest/coverage-c8": "^0.30.0",
+    "@vue/test-utils": "^2.4.0",
+    "@vue/compiler-sfc": "^3.3.0",
+    "@types/vue": "^2.0.0",
+    "vue": "^3.3.0",
+    "eslint": "^8.37.0",
+    "happy-dom": "^9.10.9",
+    "typescript": "^5.3.0",
+    "vitest": "^0.30.0",
+    "tsup": "^7.0.0"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}