@dereekb/vitest 13.5.1 → 13.6.0

package/package.json

@@ -1,10 +1,20 @@
 {
   "name": "@dereekb/vitest",
-  "version": "13.5.1",
+  "version": "13.6.0",
   "peerDependencies": {
     "@vitest/expect": "4.1.0",
+    "axe-core": "^4.11.1",
     "date-fns": "^4.0.0",
-    "vitest": "4.1.0"
+    "vitest": "4.1.0",
+    "vitest-axe": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "axe-core": {
+      "optional": true
+    },
+    "vitest-axe": {
+      "optional": true
+    }
   },
   "exports": {
     ".": {
@@ -14,6 +24,10 @@
     "./extend": {
       "types": "./src/extend.d.ts",
       "default": "./src/extend.js"
+    },
+    "./a11y": {
+      "types": "./src/a11y.d.ts",
+      "default": "./src/a11y.js"
     }
   },
   "types": "./src/index.d.ts",

package/src/a11y.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Extend entry point for vitest-axe a11y matchers.
+ *
+ * This is a separate entry point from `./extend` (which registers date matchers)
+ * because `vitest-axe` and `axe-core` are optional peer dependencies. Keeping them
+ * in a dedicated entry point means consumers who only need date matchers don't
+ * require the a11y packages to be installed.
+ *
+ * The `declare module 'vitest'` augmentation ships with the npm package so downstream
+ * consumers get types automatically. Within this workspace, `vitest.setup.typings.ts`
+ * also declares the same augmentation so the IDE resolves types from `tsconfig.spec.json`.
+ *
+ * @example
+ * ```typescript
+ * // In a vitest setup file (e.g. vitest.setup.angular.ts):
+ * import '@dereekb/vitest/a11y';
+ *
+ * const results = await axe(element);
+ * expect(results).toHaveNoViolations();
+ * ```
+ */
+import 'vitest';
+import type { AxeMatchers } from './lib/matcher.a11y.js';
+declare module 'vitest' {
+    interface Assertion extends AxeMatchers {
+    }
+    interface AsymmetricMatchersContaining extends AxeMatchers {
+    }
+}

package/src/a11y.js

@@ -0,0 +1,26 @@
+/**
+ * Extend entry point for vitest-axe a11y matchers.
+ *
+ * This is a separate entry point from `./extend` (which registers date matchers)
+ * because `vitest-axe` and `axe-core` are optional peer dependencies. Keeping them
+ * in a dedicated entry point means consumers who only need date matchers don't
+ * require the a11y packages to be installed.
+ *
+ * The `declare module 'vitest'` augmentation ships with the npm package so downstream
+ * consumers get types automatically. Within this workspace, `vitest.setup.typings.ts`
+ * also declares the same augmentation so the IDE resolves types from `tsconfig.spec.json`.
+ *
+ * @example
+ * ```typescript
+ * // In a vitest setup file (e.g. vitest.setup.angular.ts):
+ * import '@dereekb/vitest/a11y';
+ *
+ * const results = await axe(element);
+ * expect(results).toHaveNoViolations();
+ * ```
+ */
+import 'vitest';
+import { expect } from 'vitest';
+import { allA11yMatchers } from './lib/matcher.a11y.js';
+expect.extend(allA11yMatchers);
+//# sourceMappingURL=a11y.js.map

package/src/a11y.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"a11y.js","sourceRoot":"","sources":["../../../../packages/vitest/src/a11y.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,QAAQ,CAAC;AAChB,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGhC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC"}

package/src/extend.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Extend entry point for date matchers.
+ *
+ * A11y matchers (vitest-axe) are registered separately via `@dereekb/vitest/a11y`
+ * because `vitest-axe` and `axe-core` are optional peer dependencies.
+ *
+ * @see {@link file://./a11y.ts} for the a11y extend entry point.
+ */
 import 'vitest';
 import type { AllDateMatchers } from './lib/matcher.date.js';
 declare module 'vitest' {

package/src/extend.js

@@ -1,4 +1,12 @@
-// File Stucture derived from https://github.com/stschulte/aws-sdk-client-mock-vitest
+/**
+ * Extend entry point for date matchers.
+ *
+ * A11y matchers (vitest-axe) are registered separately via `@dereekb/vitest/a11y`
+ * because `vitest-axe` and `axe-core` are optional peer dependencies.
+ *
+ * @see {@link file://./a11y.ts} for the a11y extend entry point.
+ */
+// File structure derived from https://github.com/stschulte/aws-sdk-client-mock-vitest
 import 'vitest';
 import { expect } from 'vitest';
 import { allDateMatchers } from './lib/matcher.date.js';

package/src/extend.js.map

@@ -1 +1 @@
-{"version":3,"file":"extend.js","sourceRoot":"","sources":["../../../../packages/vitest/src/extend.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAErF,OAAO,QAAQ,CAAC;AAChB,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGhC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC"}
+{"version":3,"file":"extend.js","sourceRoot":"","sources":["../../../../packages/vitest/src/extend.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,sFAAsF;AAEtF,OAAO,QAAQ,CAAC;AAChB,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGhC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC"}

package/src/lib/index.d.ts

@@ -1 +1,2 @@
 export * from './matcher.date.js';
+export * from './matcher.a11y.js';

package/src/lib/index.js

@@ -1,2 +1,3 @@
 export * from './matcher.date.js';
+export * from './matcher.a11y.js';
 //# sourceMappingURL=index.js.map

package/src/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/vitest/src/lib/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/vitest/src/lib/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC"}

package/src/lib/matcher.a11y.d.ts

@@ -0,0 +1,61 @@
+import * as matchers from 'vitest-axe/matchers';
+import type AxeCore from 'axe-core';
+export type { AxeMatchers } from 'vitest-axe/matchers';
+/**
+ * Object or wrapper that exposes a native DOM element, such as Angular's `ComponentFixture`.
+ */
+export interface NativeElementRef {
+    readonly nativeElement: Element;
+}
+/**
+ * Input accepted by a11y helpers: a raw DOM element or any object exposing `nativeElement`.
+ */
+export type A11yTestTarget = Element | NativeElementRef;
+/**
+ * All vitest-axe matchers, ready to register via `expect.extend()`.
+ *
+ * @example
+ * ```typescript
+ * import { allA11yMatchers } from '@dereekb/vitest';
+ * expect.extend(allA11yMatchers);
+ *
+ * const results = await axe(document.body);
+ * expect(results).toHaveNoViolations();
+ * ```
+ */
+export declare const allA11yMatchers: typeof matchers;
+/**
+ * Runs axe-core on a target element and asserts zero accessibility violations.
+ *
+ * Accepts a raw DOM `Element` or any object with a `nativeElement` property (e.g. Angular `ComponentFixture`).
+ *
+ * @param target - Element or fixture to test.
+ * @param options - Optional axe-core run options.
+ *
+ * @example
+ * ```typescript
+ * // With Angular ComponentFixture
+ * await expectNoA11yViolations(fixture);
+ *
+ * // With raw element
+ * await expectNoA11yViolations(document.getElementById('app')!);
+ * ```
+ */
+export declare function expectNoA11yViolations(target: A11yTestTarget, options?: AxeCore.RunOptions): Promise<void>;
+/**
+ * Runs axe-core on a target element and returns the results without asserting.
+ *
+ * Useful when you need to inspect violations or filter results before asserting.
+ *
+ * @param target - Element or fixture to check.
+ * @param options - Optional axe-core run options.
+ * @returns The axe-core results object.
+ *
+ * @example
+ * ```typescript
+ * const results = await getA11yResults(fixture);
+ * const critical = results.violations.filter(v => v.impact === 'critical');
+ * expect(critical).toHaveLength(0);
+ * ```
+ */
+export declare function getA11yResults(target: A11yTestTarget, options?: AxeCore.RunOptions): Promise<AxeCore.AxeResults>;

package/src/lib/matcher.a11y.js

@@ -0,0 +1,60 @@
+import { expect } from 'vitest';
+import * as matchers from 'vitest-axe/matchers';
+import { axe } from 'vitest-axe';
+function resolveElement(target) {
+    return 'nativeElement' in target ? target.nativeElement : target;
+}
+/**
+ * All vitest-axe matchers, ready to register via `expect.extend()`.
+ *
+ * @example
+ * ```typescript
+ * import { allA11yMatchers } from '@dereekb/vitest';
+ * expect.extend(allA11yMatchers);
+ *
+ * const results = await axe(document.body);
+ * expect(results).toHaveNoViolations();
+ * ```
+ */
+export const allA11yMatchers = matchers;
+/**
+ * Runs axe-core on a target element and asserts zero accessibility violations.
+ *
+ * Accepts a raw DOM `Element` or any object with a `nativeElement` property (e.g. Angular `ComponentFixture`).
+ *
+ * @param target - Element or fixture to test.
+ * @param options - Optional axe-core run options.
+ *
+ * @example
+ * ```typescript
+ * // With Angular ComponentFixture
+ * await expectNoA11yViolations(fixture);
+ *
+ * // With raw element
+ * await expectNoA11yViolations(document.getElementById('app')!);
+ * ```
+ */
+export async function expectNoA11yViolations(target, options) {
+    const results = await axe(resolveElement(target), options);
+    expect(results).toHaveNoViolations();
+}
+/**
+ * Runs axe-core on a target element and returns the results without asserting.
+ *
+ * Useful when you need to inspect violations or filter results before asserting.
+ *
+ * @param target - Element or fixture to check.
+ * @param options - Optional axe-core run options.
+ * @returns The axe-core results object.
+ *
+ * @example
+ * ```typescript
+ * const results = await getA11yResults(fixture);
+ * const critical = results.violations.filter(v => v.impact === 'critical');
+ * expect(critical).toHaveLength(0);
+ * ```
+ */
+export async function getA11yResults(target, options) {
+    return axe(resolveElement(target), options);
+}
+//# sourceMappingURL=matcher.a11y.js.map

package/src/lib/matcher.a11y.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"matcher.a11y.js","sourceRoot":"","sources":["../../../../../packages/vitest/src/lib/matcher.a11y.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAiBjC,SAAS,cAAc,CAAC,MAAsB;IAC5C,OAAO,eAAe,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC;AACnE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,QAAQ,CAAC;AAExC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,MAAsB,EAAE,OAA4B;IAC/F,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;IAC3D,MAAM,CAAC,OAAO,CAAC,CAAC,kBAAkB,EAAE,CAAC;AACvC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAAsB,EAAE,OAA4B;IACvF,OAAO,GAAG,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;AAC9C,CAAC"}