vi-axe 0.0.1-pre-alpha → 0.0.3

package/README.md

@@ -1,329 +1,133 @@
-# vi-axe [A modern Fork / Rewrite of jest-axe]
+# vi-axe
 
-[![npm version](https://img.shields.io/npm/v/vi-axe.svg)](http://npm.im/vi-axe)
-![node](https://img.shields.io/node/v/vi-axe)
-
-# DO NOT USE THIS AS IT IS NOW.
-
-Custom [Vi][Vi] matcher for [axe](https://github.com/dequelabs/axe-core) for testing accessibility
-
-## ⚠️✋ This project does not guarantee that what you build is accessible.
-
-The GDS Accessibility team found that around [~30% of access barriers are missed by automated testing](https://accessibility.blog.gov.uk/2017/02/24/what-we-found-when-we-tested-tools-on-the-worlds-least-accessible-webpage).
+### A modern fork / rewrite of jest-axe for vitest.
 
-Tools like axe are similar to [code linters](https://en.wikipedia.org/wiki/Lint_%28software%29) such as [eslint](https://eslint.org/) or [stylelint](https://stylelint.io/): they can find common issues but cannot guarantee that what you build works for users.
+I'm aware that vitest-axe also exists, however it seems to be unmaintained.
 
-You'll also need to:
-
-- test your interface with the [assistive technologies that real users use](https://www.gov.uk/service-manual/technology/testing-with-assistive-technologies#when-to-test) (see also [WebAIM's survey results](https://webaim.org/projects/screenreadersurvey8/#primary)).
-- include disabled people in user research.
-
-### Checks that do not work in jest-axe
+[![npm version](https://img.shields.io/npm/v/vi-axe.svg)](http://npm.im/vi-axe)
+![node](https://img.shields.io/node/v/vi-axe)
 
-Color contrast checks do not work in JSDOM so are turned off in jest-axe.
+Custom Vitest matcher for [aXe](https://github.com/dequelabs/axe-core) to test accessibility in your components and pages.
 
-## Installation:
+## Installation
 
 ```bash
-npm install --save-dev jest jest-axe jest-environment-jsdom
-```
-
-[TypeScript](https://www.typescriptlang.org/) users can install the community maintained types package:
-
-```bash
-npm install --save-dev @types/jest-axe
-```
-
-## Usage:
-
-```javascript
-/**
- * @jest-environment jsdom
- */
-const { axe, toHaveNoViolations } = require("jest-axe");
-
-expect.extend(toHaveNoViolations);
-
-it("should demonstrate this matcher`s usage", async () => {
-  const render = () => '<img src="#"/>';
-
-  // pass anything that outputs html to axe
-  const html = render();
-
-  expect(await axe(html)).toHaveNoViolations();
-});
-```
-
-![Screenshot of the resulting output from the usage example](example-cli.png)
-
-> Note, you can also require `'jest-axe/extend-expect'` which will call `expect.extend` for you.
-> This is especially helpful when using the jest `setupFilesAfterEnv` configuration.
-
-### Testing React
-
-```javascript
-const React = require("react");
-const { render } = require("react-dom");
-const App = require("./app");
-
-const { axe, toHaveNoViolations } = require("jest-axe");
-expect.extend(toHaveNoViolations);
-
-it("should demonstrate this matcher`s usage with react", async () => {
-  render(<App />, document.body);
-  const results = await axe(document.body);
-  expect(results).toHaveNoViolations();
-});
+pnpm add -D vi-axe
+# or
+npm install -D vi-axe
+# or
+yarn add -D vi-axe
 ```
 
-### Testing React with [React Testing Library](https://testing-library.com/docs/react-testing-library/intro)
-
-```javascript
-const React = require("react");
-const App = require("./app");
+## Setup
 
-const { render } = require("@testing-library/react");
-const { axe, toHaveNoViolations } = require("jest-axe");
-expect.extend(toHaveNoViolations);
+Configure Vitest so the `toHaveNoViolations` matcher is available in all tests. In your Vitest config (e.g. `vitest.config.ts`):
 
-it("should demonstrate this matcher`s usage with react testing library", async () => {
-  const { container } = render(<App />);
-  const results = await axe(container);
+```ts
+import { defineConfig } from "vitest/config";
 
-  expect(results).toHaveNoViolations();
+export default defineConfig({
+  test: {
+    environment: "jsdom", // required for axe
+    setupFiles: ["vi-axe/extend-expect"],
+  },
 });
 ```
 
-> Note: If you're using `react testing library` <9.0.0 you should be using the
-> [`cleanup`](https://testing-library.com/docs/react-testing-library/api#cleanup) method. This method removes the rendered application from the DOM and ensures a clean HTML Document for further testing.
+Alternatively, in a single test file:
 
-If you're using [React Portals](https://reactjs.org/docs/portals.html), use the [`baseElement`](https://testing-library.com/docs/react-testing-library/api#baseelement) instead of `container`:
-
-```js
-it("should work with React Portals as well", async () => {
-  const { baseElement } = render(<App />);
-  const results = await axe(baseElement);
-
-  expect(results).toHaveNoViolations();
-});
+```ts
+import "vi-axe/extend-expect";
 ```
 
-### Testing Vue with [Vue Test Utils](https://vue-test-utils.vuejs.org/)
+## Usage
 
-```javascript
-const App = require("./App.vue");
+### Basic
 
-const { mount } = require("@vue/test-utils");
-const { axe, toHaveNoViolations } = require("jest-axe");
-expect.extend(toHaveNoViolations);
+Run axe on an HTML string or DOM element, then assert there are no violations:
 
-it("should demonstrate this matcher`s usage with vue test utils", async () => {
-  const wrapper = mount(Image);
-  const results = await axe(wrapper.element);
+```ts
+import { axe } from "vi-axe";
 
+test("has no a11y violations", async () => {
+  const html = `<main><a href="https://example.com">Example</a></main>`;
+  const results = await axe(html);
   expect(results).toHaveNoViolations();
 });
 ```
 
-### Testing Vue with [Vue Testing Library](https://testing-library.com/docs/vue-testing-library/intro)
+### With React Testing Library
 
-```javascript
-const App = require("./app");
+Pass the rendered container (or any element) to `axe`:
 
-const { render } = require("@testing-library/vue");
-const { axe, toHaveNoViolations } = require("jest-axe");
-expect.extend(toHaveNoViolations);
+```ts
+import { render } from "@testing-library/react";
+import { axe } from "vi-axe";
 
-it("should demonstrate this matcher`s usage with react testing library", async () => {
-  const { container } = render(<App />);
+test("component has no a11y violations", async () => {
+  const { container } = render(<MyComponent />);
   const results = await axe(container);
-
   expect(results).toHaveNoViolations();
 });
 ```
 
-> Note: If you're using `vue testing library` <3.0.0 you should be using the
-> [`cleanup`](https://testing-library.com/docs/vue-testing-library/api#cleanup) method. This method removes the rendered application from the DOM and ensures a clean HTML Document for further testing.
+### With Vue Test Utils
 
-### Testing Angular with [Nx](https://nx.dev/)
+Pass the wrapper element:
 
-```typescript
-import { ComponentFixture, TestBed } from "@angular/core/testing";
-import { axe } from "jest-axe";
-
-import { SomeComponent } from "./some.component";
-
-describe("SomeComponent", () => {
-  let fixture: ComponentFixture<SomeComponent>;
-
-  beforeEach(() => {
-    TestBed.configureTestingModule({
-      declarations: [SomeComponent],
-    });
-
-    fixture = TestBed.createComponent(SomeComponent);
-  });
-
-  it("should create", async () => {
-    const results = await axe(fixture.nativeElement);
-    expect(results).toHaveNoViolations();
-  });
-});
-```
-
-> Note: You may need to extend jest by importing `jest-axe/extend-expect` at `test-setup.ts`
-
-### Usage with jest.useFakeTimers() or mocking setTimeout
-
-> thrown: "Exceeded timeout of 5000 ms for a test.
-> Use jest.setTimeout(newTimeout) to increase the timeout value, if this is a long-running test."
-
-aXe core does not work when timers (setTimeout) are mocked. When using `jest.useFakeTimers()` aXe core will timeout often causing failing tests.
-
-We recommend renabling the timers temporarily for aXe:
-
-```javascript
-jest.useRealTimers();
-const results = await axe(wrapper.element);
-jest.useFakeTimers();
-```
-
-### Axe configuration
-
-The `axe` function allows options to be set with the [same options as documented in axe-core](https://github.com/dequelabs/axe-core/blob/master/doc/API.md#options-parameter):
-
-```javascript
-const { axe, toHaveNoViolations } = require("jest-axe");
-
-expect.extend(toHaveNoViolations);
-
-it("should demonstrate this matcher`s usage with a custom config", async () => {
-  const render = () => `
-    <div>
-      <img src="#"/>
-    </div>
-  `;
-
-  // pass anything that outputs html to axe
-  const html = render();
-
-  const results = await axe(html, {
-    rules: {
-      // for demonstration only, don't disable rules that need fixing.
-      "image-alt": { enabled: false },
-    },
-  });
+```ts
+import { mount } from "@vue/test-utils";
+import { axe } from "vi-axe";
 
+test("component has no a11y violations", async () => {
+  const wrapper = mount(MyComponent);
+  const results = await axe(wrapper.element);
   expect(results).toHaveNoViolations();
 });
 ```
 
-### Testing isolated components
-
-> All page content must be contained by landmarks (region)
+### Custom configuration
 
-When testing with aXe sometimes it assumes you are testing a page. This then results in unexpected violations for landmarks for testing isolation components.
+Use `configureAxe` to create an axe runner with default options. You can pass [axe-core run options](https://github.com/dequelabs/axe-core/blob/develop/doc/API.md) and vi-axe-specific options:
 
-You can disable this behaviour with the `region` rule:
-
-```javascript
-const { configureAxe } = require("jest-axe");
+```ts
+import { configureAxe } from "vi-axe";
 
 const axe = configureAxe({
-  rules: {
-    // disable landmark rules when testing isolated components.
-    region: { enabled: false },
-  },
-});
-```
-
-## Setting global configuration
-
-If you find yourself repeating the same options multiple times, you can export a version of the `axe` function with defaults set.
-
-Note: You can still pass additional options to this new instance; they will be merged with the defaults.
-
-This could be done in [Jest's setup step](https://jestjs.io/docs/en/setup-teardown)
-
-```javascript
-// Global helper file (axe-helper.js)
-const { configureAxe } = require("jest-axe");
-
-const axe = configureAxe({
-  rules: {
-    // for demonstration only, don't disable rules that need fixing.
-    "image-alt": { enabled: false },
+  globalOptions: {
+    rules: [{ id: "link-name", enabled: false }],
   },
 });
 
-module.exports = axe;
-```
-
-```javascript
-// Individual test file (test.js)
-const { toHaveNoViolations } = require("jest-axe");
-const axe = require("./axe-helper.js");
-
-expect.extend(toHaveNoViolations);
-
-it("should demonstrate this matcher`s usage with a default config", async () => {
-  const render = () => `
-    <div>
-      <img src="#"/>
-    </div>
-  `;
-
-  // pass anything that outputs html to axe
-  const html = render();
-
-  expect(await axe(html)).toHaveNoViolations();
+test("custom axe run", async () => {
+  const results = await axe("<a href='#'></a>");
+  expect(results).toHaveNoViolations();
 });
 ```
 
-### Setting custom rules and checks.
+Per-run options can be passed as the second argument:
 
-The configuration object passed to `configureAxe`, accepts a `globalOptions` property to configure the format of the data used by axe and to add custom checks and rules. The property value is the same as the parameter passed to [axe.configure](https://github.com/dequelabs/axe-core/blob/master/doc/API.md#parameters-1).
-
-```javascript
-// Global helper file (axe-helper.js)
-const { configureAxe } = require("jest-axe");
-
-const axe = configureAxe({
-  globalOptions: {
-    checks: [
-      /* custom checks definitions */
-    ],
-  },
-  // ...
+```ts
+const results = await axe(html, {
+  rules: { "link-name": { enabled: false } },
 });
-
-module.exports = axe;
 ```
 
-### Setting the level of user impact.
+### Filtering by impact level
 
-An array which defines which [impact](https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md) level should be considered. This ensures that only violations with a specific impact on the user are considered. The level of impact can be "minor", "moderate", "serious", or "critical".
+To fail only for certain impact levels (e.g. critical/serious), use `impactLevels` in `configureAxe`. The matcher will then consider only violations with those impacts:
 
-```javascript
-// Global helper file (axe-helper.js)
-const { configureAxe } = require("jest-axe");
+```ts
+import { configureAxe } from "vi-axe";
 
 const axe = configureAxe({
-  impactLevels: ["critical"],
-  // ...
+  impactLevels: ["critical", "serious"],
 });
-
-module.exports = axe;
 ```
 
-Refer to [Developing Axe-core Rules](https://github.com/dequelabs/axe-core/blob/master/doc/rule-development.md) for instructions on how to develop custom rules and checks.
-
-## Thanks
+## Requirements
 
-- [Jest][Jest] for the great test runner that allows extending matchers.
-- [axe](https://www.deque.com/axe/) for the wonderful axe-core that makes it so easy to do this.
-- Government Digital Service for making coding in the open the default.
-  - GOV.UK Publishing Frontend team who published the [basis of the aXe reporter](https://github.com/alphagov/govuk_publishing_components/blob/581c22c9d35d85d5d985571d007f6397a4399f4c/spec/javascripts/govuk_publishing_components/AccessibilityTestSpec.js)
-- [jest-image-snapshot](https://github.com/americanexpress/jest-image-snapshot) for inspiration on README and repo setup
+- **Node**: >= 20
+- **Vitest** with **jsdom** (or another DOM environment); axe needs a DOM to run.
 
-[Jest]: https://jestjs.io/
+Color contrast rules are disabled by default in vi-axe because they do not work reliably in jsdom.

package/dist/{src/axe-utils.d.ts → axe-utils.d.ts}

@@ -1,24 +1,23 @@
 import { AxeResults, ImpactValue, RunOptions } from "axe-core";
 /** Global options passed to axe.configure (vi-axe uses rules array) */
 interface GlobalAxeOptions {
-    rules?: Array<{
-        id: string;
-        enabled: boolean;
-    }>;
-    [key: string]: unknown;
+	rules?: Array<{
+		id: string;
+		enabled: boolean;
+	}>;
+	[key: string]: unknown;
 }
 /** Options for configureAxe: globalOptions plus runner options (impactLevels is vi-axe specific) */
 interface ConfigureAxeOptions {
-    globalOptions?: GlobalAxeOptions;
-    impactLevels?: ImpactValue[];
+	globalOptions?: GlobalAxeOptions;
+	impactLevels?: ImpactValue[];
 }
 type HtmlInput = Element | string;
 /**
- * Small wrapper for axe-core#run that enables promises (required for Jest),
- * default options and injects html to be tested
- * @param options default options to use in all instances
- * @returns returns instance of axe
- */
+* Small wrapper for axe-core#run that enables promises (required for Jest),
+* default options and injects html to be tested
+* @param options default options to use in all instances
+* @returns returns instance of axe
+*/
 export declare function configureAxe(options?: ConfigureAxeOptions & RunOptions): (html: HtmlInput, additionalOptions?: RunOptions) => Promise<AxeResults>;
 export {};
-//# sourceMappingURL=axe-utils.d.ts.map

package/dist/extend-expect.d.ts

@@ -0,0 +1,7 @@
+interface AxeMatchers<TReturn = unknown> {
+	toHaveNoViolations: () => TReturn;
+}
+declare module "vitest" {
+	interface Matchers<T = any> extends AxeMatchers<T> {}
+}
+export {};

package/dist/extend-expect.js

@@ -0,0 +1,2 @@
+import { toHaveNoViolations as o } from "./index.js";
+expect.extend(o);

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import { ImpactValue, Result, RunOptions } from "axe-core";
+import { configureAxe } from "./axe-utils.js";
+/** Minimal axe results shape accepted by the matcher (vi-axe allows toolOptions.impactLevels) */
+interface AxeResultsLike {
+	violations?: Result[];
+	toolOptions?: RunOptions & {
+		impactLevels?: ImpactValue[];
+	};
+}
+/** Matcher result returned by toHaveNoViolations */
+interface MatcherResult {
+	actual: Result[];
+	message: () => string | undefined;
+	pass: boolean;
+}
+/** Vitest/Jest matcher object for toHaveNoViolations */
+interface ToHaveNoViolationsMatcher {
+	toHaveNoViolations(results: AxeResultsLike): MatcherResult;
+}
+/**
+* Custom Jest expect matcher, that can check aXe results for violations.
+* @param results requires an instance of aXe's results object
+* @returns returns Jest matcher object
+*/
+declare const toHaveNoViolations: ToHaveNoViolationsMatcher;
+export type { AxeResultsLike };
+export { configureAxe, toHaveNoViolations };
+export declare const axe: ReturnType<typeof configureAxe>;