vi-axe 0.0.1-pre-alpha

package/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (C) 2017 Crown Copyright (Government Digital Service)
+
+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,329 @@
+# vi-axe [A modern Fork / Rewrite of 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)
+
+# 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).
+
+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.
+
+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
+
+Color contrast checks do not work in JSDOM so are turned off in jest-axe.
+
+## 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();
+});
+```
+
+### Testing React with [React Testing Library](https://testing-library.com/docs/react-testing-library/intro)
+
+```javascript
+const React = require("react");
+const App = require("./app");
+
+const { render } = require("@testing-library/react");
+const { axe, toHaveNoViolations } = require("jest-axe");
+expect.extend(toHaveNoViolations);
+
+it("should demonstrate this matcher`s usage with react testing library", async () => {
+  const { container } = render(<App />);
+  const results = await axe(container);
+
+  expect(results).toHaveNoViolations();
+});
+```
+
+> 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.
+
+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();
+});
+```
+
+### Testing Vue with [Vue Test Utils](https://vue-test-utils.vuejs.org/)
+
+```javascript
+const App = require("./App.vue");
+
+const { mount } = require("@vue/test-utils");
+const { axe, toHaveNoViolations } = require("jest-axe");
+expect.extend(toHaveNoViolations);
+
+it("should demonstrate this matcher`s usage with vue test utils", async () => {
+  const wrapper = mount(Image);
+  const results = await axe(wrapper.element);
+
+  expect(results).toHaveNoViolations();
+});
+```
+
+### Testing Vue with [Vue Testing Library](https://testing-library.com/docs/vue-testing-library/intro)
+
+```javascript
+const App = require("./app");
+
+const { render } = require("@testing-library/vue");
+const { axe, toHaveNoViolations } = require("jest-axe");
+expect.extend(toHaveNoViolations);
+
+it("should demonstrate this matcher`s usage with react testing library", async () => {
+  const { container } = render(<App />);
+  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.
+
+### Testing Angular with [Nx](https://nx.dev/)
+
+```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 },
+    },
+  });
+
+  expect(results).toHaveNoViolations();
+});
+```
+
+### Testing isolated components
+
+> All page content must be contained by landmarks (region)
+
+When testing with aXe sometimes it assumes you are testing a page. This then results in unexpected violations for landmarks for testing isolation components.
+
+You can disable this behaviour with the `region` rule:
+
+```javascript
+const { configureAxe } = require("jest-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 },
+  },
+});
+
+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();
+});
+```
+
+### Setting custom rules and checks.
+
+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 */
+    ],
+  },
+  // ...
+});
+
+module.exports = axe;
+```
+
+### Setting the level of user impact.
+
+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".
+
+```javascript
+// Global helper file (axe-helper.js)
+const { configureAxe } = require("jest-axe");
+
+const axe = configureAxe({
+  impactLevels: ["critical"],
+  // ...
+});
+
+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
+
+- [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
+
+[Jest]: https://jestjs.io/

package/dist/src/__tests__/axe-utils.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=axe-utils.test.d.ts.map

package/dist/src/__tests__/axe-utils.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"axe-utils.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/axe-utils.test.ts"],"names":[],"mappings":""}

package/dist/src/__tests__/reactjs.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=reactjs.test.d.ts.map

package/dist/src/__tests__/reactjs.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reactjs.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/reactjs.test.ts"],"names":[],"mappings":""}

package/dist/src/__tests__/vuejs.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=vuejs.test.d.ts.map

package/dist/src/__tests__/vuejs.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vuejs.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/vuejs.test.ts"],"names":[],"mappings":""}

package/dist/src/axe-utils.d.ts

@@ -0,0 +1,24 @@
+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;
+}
+/** Options for configureAxe: globalOptions plus runner options (impactLevels is vi-axe specific) */
+interface ConfigureAxeOptions {
+    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
+ */
+export declare function configureAxe(options?: ConfigureAxeOptions & RunOptions): (html: HtmlInput, additionalOptions?: RunOptions) => Promise<AxeResults>;
+export {};
+//# sourceMappingURL=axe-utils.d.ts.map

package/dist/src/axe-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"axe-utils.d.ts","sourceRoot":"","sources":["../../src/axe-utils.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAGxE,uEAAuE;AACvE,UAAU,gBAAgB;IACxB,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAChD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,oGAAoG;AACpG,UAAU,mBAAmB;IAC3B,aAAa,CAAC,EAAE,gBAAgB,CAAC;IACjC,YAAY,CAAC,EAAE,WAAW,EAAE,CAAC;CAC9B;AAED,KAAK,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;AAsDlC;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAmB,GAAG,UAAe,IA0BrD,MAAM,SAAS,EAAE,oBAAmB,UAAe,KAAG,OAAO,CAAC,UAAU,CAAC,CAc9F"}

package/dist/src/extend-expect.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=extend-expect.d.ts.map

package/dist/src/extend-expect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extend-expect.d.ts","sourceRoot":"","sources":["../../src/extend-expect.ts"],"names":[],"mappings":""}

package/dist/src/index.d.ts

@@ -0,0 +1,28 @@
+import "./types/global.d.ts";
+import { ImpactValue, Result, RunOptions } from "axe-core";
+import { configureAxe } from "./axe-utils";
+/** 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;
+}
+/**
+ * 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: {
+    toHaveNoViolations(results: AxeResultsLike): MatcherResult;
+};
+export type { AxeResultsLike };
+export { configureAxe, toHaveNoViolations };
+export declare const axe: (html: string | Element, additionalOptions?: RunOptions) => Promise<import("axe-core").AxeResults>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAE7B,OAAO,EAAE,WAAW,EAAc,MAAM,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAGvE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,iGAAiG;AACjG,UAAU,cAAc;IACtB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,CAAC,EAAE,UAAU,GAAG;QAAE,YAAY,CAAC,EAAE,WAAW,EAAE,CAAA;KAAE,CAAC;CAC7D;AAoBD,oDAAoD;AACpD,UAAU,aAAa;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAClC,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;GAIG;AACH,QAAA,MAAM,kBAAkB;gCACM,cAAc,GAAG,aAAa;CA+D3D,CAAC;AAEF,YAAY,EAAE,cAAc,EAAE,CAAC;AAC/B,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,CAAC;AAC5C,eAAO,MAAM,GAAG,oGAAiB,CAAC"}