[!WARNING] CortexUI has been renamed to DOMglyph.

@cortexui/testing is no longer maintained. All future development, bug fixes, and releases happen under the new package:

➜ @domglyph/testing — starting at v2.0.0

Please migrate at your earliest convenience:

npm uninstall @cortexui/testing
npm install @domglyph/testing

Then update all imports from '@cortexui/testing' to '@domglyph/testing'.

@cortexui/testing (deprecated)

AI contract validation and testing utilities for CortexUI.

Overview

@cortexui/testing gives you everything you need to verify that components correctly implement the CortexUI 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

npm install --save-dev @cortexui/testing

API Reference

validateAIContractNode(element)

Validates all data-ai-* attributes on a DOM element against the CortexUI AI contract specification. Returns a result object — does not throw.

import { validateAIContractNode } from '@cortexui/testing';

const result = validateAIContractNode(element);
// {
//   valid: boolean,
//   errors: string[],
//   attributes: AIAttributeMap
// }

Example:

import { validateAIContractNode } from '@cortexui/testing';
import { render, screen } from '@testing-library/react';
import { ActionButton } from '@cortexui/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:

// 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.

import { runComponentComplianceChecks } from '@cortexui/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:

import { registerCortexMatchers } from '@cortexui/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.

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.

expect(element).toHaveAIAttributes({
  'data-ai-role': 'action',
  'data-ai-action': 'save-profile',
  'data-ai-state': 'idle',
});

toPassAccessibilityChecks()

Asserts that the element passes the CortexUI accessibility audit.

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.

import { createActionFixture, createStatusFixture, createFieldFixture, createFormFixture } from '@cortexui/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:

import { runAccessibilityChecks } from '@cortexui/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:

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 '@cortexui/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 CortexUI

@cortexui/testing is part of the CortexUI design system.

• Main repository
• Documentation
• Contributing