@domglyph/testing 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 llcortex
+
+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.

package/README.md

@@ -0,0 +1,284 @@
+# @domglyph/testing  (formerly [@cortexui/testing](https://www.npmjs.com/package/@cortexui/testing))
+
+[![npm version](https://img.shields.io/npm/v/@domglyph/testing?color=0ea5e9)](https://www.npmjs.com/package/@domglyph/testing)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](../../LICENSE)
+
+AI contract validation and testing utilities for DOMglyph.
+
+---
+
+## Overview
+
+`@domglyph/testing` gives you everything you need to verify that components correctly implement the DOMglyph AI contract. It includes:
+
+- **`validateAIContractNode`** — validates `data-ai-*` attributes on a DOM element
+- **`runComponentComplianceChecks`** — full compliance check combining AI contract and accessibility
+- **Vitest matchers** — `toBeAIContractValid`, `toHaveAIAttributes`, `toPassAccessibilityChecks`
+- **Test fixtures** — pre-built DOM elements for unit testing contract validators
+- **`runAccessibilityChecks`** — accessibility audit for individual elements
+
+---
+
+## Installation
+
+```bash
+npm install --save-dev @domglyph/testing
+```
+
+---
+
+## API Reference
+
+### validateAIContractNode(element)
+
+Validates all `data-ai-*` attributes on a DOM element against the DOMglyph AI contract specification. Returns a result object — does not throw.
+
+```ts
+import { validateAIContractNode } from '@domglyph/testing';
+
+const result = validateAIContractNode(element);
+// {
+//   valid: boolean,
+//   errors: string[],
+//   attributes: AIAttributeMap
+// }
+```
+
+Example:
+
+```ts
+import { validateAIContractNode } from '@domglyph/testing';
+import { render, screen } from '@testing-library/react';
+import { ActionButton } from '@domglyph/components';
+
+render(<ActionButton action="save-profile" state="idle" label="Save" />);
+const btn = screen.getByRole('button');
+
+const result = validateAIContractNode(btn);
+// { valid: true, errors: [], attributes: { role: 'action', id: 'save-profile', state: 'idle', ... } }
+```
+
+When there are violations:
+
+```ts
+// A button with data-ai-role="action" but no data-ai-id or data-ai-action
+const result = validateAIContractNode(badElement);
+// {
+//   valid: false,
+//   errors: [
+//     'Elements with data-ai-role="action" must have data-ai-id',
+//     'Elements with data-ai-role="action" must have data-ai-action'
+//   ],
+//   attributes: { role: 'action', id: null, action: null, state: null, ... }
+// }
+```
+
+---
+
+### runComponentComplianceChecks(element, options)
+
+Runs a full compliance check that covers both the AI contract and accessibility requirements. Useful for a single comprehensive assertion in integration tests.
+
+```ts
+import { runComponentComplianceChecks } from '@domglyph/testing';
+
+const result = runComponentComplianceChecks(element, {
+  requiredAttributes: ['data-ai-id', 'data-ai-role', 'data-ai-state'],
+  requiredAriaAttributes: ['aria-label'],
+});
+// {
+//   valid: boolean,
+//   contractErrors: string[],
+//   accessibilityErrors: string[]
+// }
+```
+
+---
+
+### Vitest Matchers
+
+Register custom matchers to write expressive assertions:
+
+```ts
+import { registerCortexMatchers } from '@domglyph/testing';
+import { expect } from 'vitest';
+
+// Call once in your vitest setup file (vitest.setup.ts)
+registerCortexMatchers(expect);
+```
+
+Once registered, the following matchers are available on any DOM element:
+
+#### `toBeAIContractValid()`
+
+Asserts that the element passes full AI contract validation.
+
+```ts
+expect(element).toBeAIContractValid();
+// Fails with: "Expected element to have a valid AI contract, but found 2 error(s): ..."
+```
+
+#### `toHaveAIAttributes(attributes)`
+
+Asserts that the element has specific `data-ai-*` attribute values.
+
+```ts
+expect(element).toHaveAIAttributes({
+  'data-ai-role': 'action',
+  'data-ai-action': 'save-profile',
+  'data-ai-state': 'idle',
+});
+```
+
+#### `toPassAccessibilityChecks()`
+
+Asserts that the element passes the DOMglyph accessibility audit.
+
+```ts
+expect(element).toPassAccessibilityChecks();
+```
+
+---
+
+### Test Fixtures
+
+Fixtures create valid DOM elements with AI contract attributes. Use them for testing validators, matchers, and utilities without needing to render full components.
+
+```ts
+import { createActionFixture, createStatusFixture, createFieldFixture, createFormFixture } from '@domglyph/testing';
+
+// Creates a <button> with data-ai-role="action" and the given props
+const btn = createActionFixture({ action: 'save-profile', state: 'idle' });
+
+// Creates a <div> with data-ai-role="status" and the given type
+const banner = createStatusFixture({ type: 'success', message: 'Saved!' });
+
+// Creates an <input> with data-ai-role="field"
+const input = createFieldFixture({ id: 'user-email', fieldType: 'email', required: true });
+
+// Creates a <form> element with data-ai-role="form"
+const form = createFormFixture({ id: 'contact-form' });
+```
+
+---
+
+### runAccessibilityChecks(element)
+
+Runs a focused accessibility audit on a single element and returns any violations:
+
+```ts
+import { runAccessibilityChecks } from '@domglyph/testing';
+
+const result = runAccessibilityChecks(element);
+// {
+//   passed: boolean,
+//   violations: Array<{
+//     rule: string,
+//     message: string,
+//     impact: 'critical' | 'serious' | 'moderate' | 'minor'
+//   }>
+// }
+```
+
+---
+
+## Example Test Suite
+
+A complete test file for a custom component, covering AI contract compliance, state transitions, and accessibility:
+
+```ts
+import { describe, test, expect, beforeAll } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { validateAIContractNode, runAccessibilityChecks, registerCortexMatchers } from '@domglyph/testing';
+import { MyButton } from '../src/MyButton';
+
+beforeAll(() => {
+  registerCortexMatchers(expect);
+});
+
+describe('MyButton', () => {
+  describe('AI contract', () => {
+    test('has a valid AI contract in idle state', () => {
+      render(<MyButton action="confirm-order" state="idle" label="Confirm order" />);
+      const btn = screen.getByRole('button');
+      const result = validateAIContractNode(btn);
+      expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    });
+
+    test('has the correct data-ai-* attributes', () => {
+      render(<MyButton action="confirm-order" state="idle" label="Confirm order" />);
+      const btn = screen.getByRole('button');
+      expect(btn).toHaveAIAttributes({
+        'data-ai-role': 'action',
+        'data-ai-id': 'confirm-order',
+        'data-ai-action': 'confirm-order',
+        'data-ai-state': 'idle',
+      });
+    });
+
+    test('passes full contract validation', () => {
+      render(<MyButton action="confirm-order" state="idle" label="Confirm order" />);
+      expect(screen.getByRole('button')).toBeAIContractValid();
+    });
+  });
+
+  describe('state transitions', () => {
+    test('reflects loading state in data-ai-state', () => {
+      const { rerender } = render(
+        <MyButton action="confirm-order" state="idle" label="Confirm order" />
+      );
+      expect(screen.getByRole('button')).toHaveAttribute('data-ai-state', 'idle');
+
+      rerender(<MyButton action="confirm-order" state="loading" label="Confirm order" />);
+      expect(screen.getByRole('button')).toHaveAttribute('data-ai-state', 'loading');
+    });
+
+    test('reflects error state in data-ai-state', () => {
+      const { rerender } = render(
+        <MyButton action="confirm-order" state="idle" label="Confirm order" />
+      );
+      rerender(<MyButton action="confirm-order" state="error" label="Confirm order" />);
+      expect(screen.getByRole('button')).toHaveAttribute('data-ai-state', 'error');
+    });
+
+    test('is disabled in loading state', () => {
+      render(<MyButton action="confirm-order" state="loading" label="Confirm order" />);
+      expect(screen.getByRole('button')).toBeDisabled();
+    });
+  });
+
+  describe('accessibility', () => {
+    test('passes accessibility checks', () => {
+      render(<MyButton action="confirm-order" state="idle" label="Confirm order" />);
+      expect(screen.getByRole('button')).toPassAccessibilityChecks();
+    });
+
+    test('has accessible name from label', () => {
+      render(<MyButton action="confirm-order" state="idle" label="Confirm order" />);
+      expect(screen.getByRole('button', { name: 'Confirm order' })).toBeInTheDocument();
+    });
+  });
+});
+```
+
+---
+
+## Part of DOMglyph
+
+`@domglyph/testing` is part of the [DOMglyph](../../README.md) design system.
+
+- [Main repository](../../README.md)
+- [Documentation](http://localhost:3001/docs/testing)
+- [Contributing](../../CONTRIBUTING.md)
+
+---
+
+## ☕ Support
+
+If you find DOMglyph useful, you can support the project:
+
+👉 https://buymeacoffee.com/nishchya
+
+It helps keep the project alive and growing.

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+import { AIRole, AIState, AIAttributeValidationResult, AIAttributeMap, AIAttributeElement, validateAIAttributes, extractAIAttributes } from '@domglyph/ai-contract';
+import { ExpectStatic } from 'vitest';
+
+interface TestHarness {
+    readonly name: string;
+    readonly runner: "vitest";
+}
+interface VirtualAttribute {
+    readonly name: string;
+    readonly value: string;
+}
+interface VirtualElementOptions {
+    readonly tagName?: string;
+    readonly textContent?: string;
+    readonly hidden?: boolean;
+    readonly attributes?: Record<string, string | undefined>;
+}
+interface VirtualElement extends AIAttributeElement {
+    readonly tagName: string;
+    readonly textContent: string;
+    readonly hidden: boolean;
+    readonly attributes: readonly VirtualAttribute[];
+    getAttribute(name: string): string | null;
+    hasAttribute(name: string): boolean;
+}
+interface ContractCheckResult {
+    readonly valid: boolean;
+    readonly errors: readonly string[];
+    readonly attributes: AIAttributeMap;
+}
+interface AccessibilityCheckOptions {
+    readonly expectedRole?: AIRole;
+    readonly requireAccessibleName?: boolean;
+}
+interface AccessibilityCheckResult {
+    readonly valid: boolean;
+    readonly errors: readonly string[];
+}
+interface ComplianceCheckOptions extends AccessibilityCheckOptions {
+    readonly requiredAttributes?: readonly string[];
+    readonly allowedStates?: readonly AIState[];
+}
+interface ComplianceCheckResult {
+    readonly valid: boolean;
+    readonly contract: AIAttributeValidationResult;
+    readonly accessibility: AccessibilityCheckResult;
+    readonly errors: readonly string[];
+}
+interface MetadataSnapshot {
+    readonly target: string;
+    readonly attributes: AIAttributeMap;
+}
+
+declare function runAccessibilityChecks(element: ElementLike$2, options?: AccessibilityCheckOptions): AccessibilityCheckResult;
+type ElementLike$2 = {
+    readonly textContent?: string;
+    getAttribute?: (name: string) => string | null;
+    readonly [key: string]: unknown;
+};
+
+declare function validateAIContractNode(element: ElementLike$1): ContractCheckResult;
+declare function runComponentComplianceChecks(element: ElementLike$1, options?: ComplianceCheckOptions): ComplianceCheckResult;
+type ElementLike$1 = Parameters<typeof validateAIAttributes>[0];
+
+declare function createVirtualElement(options?: VirtualElementOptions): VirtualElement;
+
+declare function createActionFixture(): VirtualElement;
+declare function createStatusFixture(): VirtualElement;
+
+declare const cortexMatchers: {
+    toBeAIContractValid(received: ElementLike): {
+        message: () => string;
+        pass: boolean;
+    };
+    toHaveAIAttributes(received: ElementLike, expected: Record<string, string>): {
+        message: () => string;
+        pass: boolean;
+    };
+    toPassAccessibilityChecks(received: ElementLike): {
+        message: () => string;
+        pass: boolean;
+    };
+    toMatchAIMetadataSnapshot(received: {
+        readonly target: string;
+        readonly attributes: Record<string, string | undefined>;
+    }, expected: string): {
+        message: () => string;
+        pass: boolean;
+    };
+};
+declare function registerCortexMatchers(expect: ExpectStatic): void;
+type ElementLike = Parameters<typeof validateAIAttributes>[0];
+
+declare function createMetadataSnapshot(target: string, element: Parameters<typeof extractAIAttributes>[0]): MetadataSnapshot;
+declare function serializeMetadataSnapshot(snapshot: MetadataSnapshot): string;
+
+declare const harness: TestHarness;
+
+export { type AccessibilityCheckOptions, type AccessibilityCheckResult, type ComplianceCheckOptions, type ComplianceCheckResult, type ContractCheckResult, type MetadataSnapshot, type TestHarness, type VirtualAttribute, type VirtualElement, type VirtualElementOptions, cortexMatchers, createActionFixture, createMetadataSnapshot, createStatusFixture, createVirtualElement, harness, registerCortexMatchers, runAccessibilityChecks, runComponentComplianceChecks, serializeMetadataSnapshot, validateAIContractNode };

package/dist/index.js

@@ -0,0 +1,220 @@
+// src/accessibility.ts
+import { DATA_AI_ROLE } from "@domglyph/ai-contract";
+function runAccessibilityChecks(element, options = {}) {
+  const errors = [];
+  const role = readAttribute(element, "role") ?? readAttribute(element, DATA_AI_ROLE);
+  const accessibleName = readAttribute(element, "aria-label") ?? readAttribute(element, "title") ?? readTextContent(element);
+  if (options.expectedRole && role !== options.expectedRole) {
+    errors.push(`Expected accessible role "${options.expectedRole}" but received "${role ?? "none"}".`);
+  }
+  if (options.requireAccessibleName !== false && (!accessibleName || accessibleName.trim() === "")) {
+    errors.push("Accessible name is required.");
+  }
+  if (readAttribute(element, "aria-hidden") === "true" && accessibleName) {
+    errors.push("aria-hidden content should not be used as an accessible target.");
+  }
+  return {
+    errors,
+    valid: errors.length === 0
+  };
+}
+function readAttribute(element, name) {
+  const value = element.getAttribute?.(name);
+  if (value !== null && value !== void 0) {
+    return value;
+  }
+  const recordValue = element[name];
+  return typeof recordValue === "string" ? recordValue : void 0;
+}
+function readTextContent(element) {
+  return typeof element.textContent === "string" ? element.textContent : void 0;
+}
+
+// src/contract.ts
+import {
+  DATA_AI_ID,
+  DATA_AI_ROLE as DATA_AI_ROLE2,
+  DATA_AI_STATE,
+  extractAIAttributes,
+  validateAIAttributes
+} from "@domglyph/ai-contract";
+function validateAIContractNode(element) {
+  const result = validateAIAttributes(element);
+  return {
+    attributes: result.attributes,
+    errors: result.errors,
+    valid: result.valid
+  };
+}
+function runComponentComplianceChecks(element, options = {}) {
+  const contract = validateAIAttributes(element);
+  const accessibility = runAccessibilityChecks(element, options);
+  const metadata = extractAIAttributes(element);
+  const errors = [...contract.errors, ...accessibility.errors];
+  for (const name of options.requiredAttributes ?? []) {
+    if (metadata[name] === void 0) {
+      errors.push(`${name} is required for component compliance.`);
+    }
+  }
+  if (options.allowedStates && metadata[DATA_AI_STATE] !== void 0) {
+    const states = metadata[DATA_AI_STATE]?.split(",").map((state) => state.trim()).filter(Boolean) ?? [];
+    for (const state of states) {
+      if (!options.allowedStates.includes(state)) {
+        errors.push(`${DATA_AI_STATE} contains unsupported state "${state}".`);
+      }
+    }
+  }
+  if (metadata[DATA_AI_ROLE2] === void 0 && metadata[DATA_AI_ID] !== void 0) {
+    errors.push(`${DATA_AI_ROLE2} is required when ${DATA_AI_ID} is present.`);
+  }
+  return {
+    accessibility,
+    contract,
+    errors,
+    valid: errors.length === 0
+  };
+}
+
+// src/dom.ts
+function createVirtualElement(options = {}) {
+  const attributes = Object.entries(options.attributes ?? {}).filter((entry) => typeof entry[1] === "string").map(([name, value]) => ({ name, value }));
+  return {
+    attributes,
+    dataset: Object.fromEntries(
+      attributes.filter((attribute) => attribute.name.startsWith("data-")).map((attribute) => [toDatasetKey(attribute.name), attribute.value])
+    ),
+    getAttribute(name) {
+      return attributes.find((attribute) => attribute.name === name)?.value ?? null;
+    },
+    hasAttribute(name) {
+      return attributes.some((attribute) => attribute.name === name);
+    },
+    hidden: options.hidden ?? false,
+    tagName: options.tagName ?? "div",
+    textContent: options.textContent ?? ""
+  };
+}
+function toDatasetKey(name) {
+  return name.replace(/^data-/, "").split("-").map((part, index) => index === 0 ? part : `${part[0]?.toUpperCase() ?? ""}${part.slice(1)}`).join("");
+}
+
+// src/fixtures.ts
+import {
+  AIEvent,
+  AIRole,
+  AIState,
+  createAIAttributes
+} from "@domglyph/ai-contract";
+function createActionFixture() {
+  return createVirtualElement({
+    attributes: {
+      ...createAIAttributes({
+        action: {
+          expectedOutcome: "Profile saved",
+          id: "save-profile",
+          name: "Save profile"
+        },
+        id: "save-profile-button",
+        role: AIRole.ACTION,
+        state: [AIState.IDLE]
+      }),
+      "aria-label": "Save profile",
+      role: "button"
+    },
+    tagName: "button",
+    textContent: "Save profile"
+  });
+}
+function createStatusFixture() {
+  return createVirtualElement({
+    attributes: {
+      ...createAIAttributes({
+        event: AIEvent.ACTION_COMPLETED,
+        id: "save-status",
+        role: AIRole.STATUS,
+        state: AIState.SUCCESS,
+        status: "success"
+      }),
+      role: "status"
+    },
+    textContent: "Profile saved"
+  });
+}
+
+// src/matchers.ts
+import { extractAIAttributes as extractAIAttributes3, validateAIAttributes as validateAIAttributes2 } from "@domglyph/ai-contract";
+
+// src/snapshot.ts
+import { extractAIAttributes as extractAIAttributes2 } from "@domglyph/ai-contract";
+function createMetadataSnapshot(target, element) {
+  return {
+    attributes: extractAIAttributes2(element),
+    target
+  };
+}
+function serializeMetadataSnapshot(snapshot) {
+  return JSON.stringify(snapshot, null, 2);
+}
+
+// src/matchers.ts
+var cortexMatchers = {
+  toBeAIContractValid(received) {
+    const validation = validateAIAttributes2(received);
+    return {
+      message: () => validation.valid ? "Expected AI contract validation to fail." : `Expected AI contract to be valid.
+${validation.errors.join("\n")}`,
+      pass: validation.valid
+    };
+  },
+  toHaveAIAttributes(received, expected) {
+    const attributes = extractAIAttributes3(received);
+    const missing = Object.entries(expected).filter(([key, value]) => attributes[key] !== value);
+    return {
+      message: () => missing.length === 0 ? "Expected AI attribute assertion to fail." : `Missing or mismatched attributes:
+${missing.map(([key, value]) => `${key}: ${value}`).join("\n")}`,
+      pass: missing.length === 0
+    };
+  },
+  toPassAccessibilityChecks(received) {
+    const result = runAccessibilityChecks(received);
+    return {
+      message: () => result.valid ? "Expected accessibility checks to fail." : `Expected element to pass accessibility checks.
+${result.errors.join("\n")}`,
+      pass: result.valid
+    };
+  },
+  toMatchAIMetadataSnapshot(received, expected) {
+    const actual = serializeMetadataSnapshot({
+      attributes: received.attributes,
+      target: received.target
+    });
+    return {
+      message: () => `Expected metadata snapshot to match.
+Actual:
+${actual}`,
+      pass: actual === expected
+    };
+  }
+};
+function registerCortexMatchers(expect) {
+  expect.extend(cortexMatchers);
+}
+
+// src/index.ts
+var harness = {
+  name: "domglyph-ai-testkit",
+  runner: "vitest"
+};
+export {
+  cortexMatchers,
+  createActionFixture,
+  createMetadataSnapshot,
+  createStatusFixture,
+  createVirtualElement,
+  harness,
+  registerCortexMatchers,
+  runAccessibilityChecks,
+  runComponentComplianceChecks,
+  serializeMetadataSnapshot,
+  validateAIContractNode
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@domglyph/testing",
+  "version": "2.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@domglyph/components": "2.0.0",
+    "@domglyph/ai-contract": "2.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "lint": "eslint src --ext .ts",
+    "test": "vitest run",
+    "typecheck": "tsc -b"
+  }
+}