From 6daa04e888f2df947168f9b9bc854a06d2b6e0fe Mon Sep 17 00:00:00 2001 From: Jean-Yves Moyen Date: Wed, 23 Oct 2024 10:00:28 +0200 Subject: [PATCH] Add Code Checker documentation --- accessibility-code-checker/README.md | 52 +++++++++++++++++++ accessibility-code-checker/cypress/README.md | 13 +++++ .../cypress/test/cypress.spec.ts | 5 ++ .../playwright/README.md | 11 ++++ .../playwright/test/playwright.spec.ts | 5 ++ 5 files changed, 86 insertions(+) create mode 100644 accessibility-code-checker/README.md create mode 100644 accessibility-code-checker/cypress/README.md create mode 100644 accessibility-code-checker/playwright/README.md diff --git a/accessibility-code-checker/README.md b/accessibility-code-checker/README.md new file mode 100644 index 0000000..4523d4f --- /dev/null +++ b/accessibility-code-checker/README.md @@ -0,0 +1,52 @@ +# Accessibility Code Checker + +These workspaces demonstrate how to use Siteimprove's Accessibility Code Checker with various browser automations. + +You can clone this repository to have a working setup on your local computer from which you can easily experiment. + +## Setup + +From [the top-level of the repository](..), install dependencies and build the project: + +```bash +$ yarn install +$ yarn build +``` + +## Starting the server + +From [the top-level of the repository](..), start the server: + +```bash +$ yarn code-checker:start +``` + +This will start a local server on `localhost:5173`. The associated code lives in the [demo-page](./demo-page) workspace. The server will watch any changes, so you can edit the page and see the results. Note that the page is voluntarily inaccessible since it is used to demonstrate how the Accessibility Code Checker can help you find accessibility issues. + +## Running the Accessibility Code Checker + +From another terminal at [the top-level of the repository](..), run the Accessibility Code Checker: + +```bash +$ yarn code-checker:test +``` + +> **Note:** these tests are expected to fail since the demo page is intentionally inaccessible. + +This will run the Accessibility Code Checker for all the existing integrations, namely: +* [Cypress](./cypress) +* [Playwright](./playwright) + +If you which to only run for one of them, run, e.g.: + +```bash +$ yarn workspace code-checker-playwright test +``` + +The examples are reading credentials for the Siteimprove Intelligence Platform from the environment variables `SI_USER_EMAIL` and `SI_API_KEY`. See [the associated documentation](https://alfa.siteimprove.com/code-checker/getting-started/reporting#sip) for how to create an API key for the Siteimprove Intelligence Platform. + +If no credentials are provided, a summary of the results will be logged in the console. + +## Experimenting + +Each workspace in this directory contains one full example of integration. Among other, you can change the page URL to try the Accessibility Code Checker on a different page. \ No newline at end of file diff --git a/accessibility-code-checker/cypress/README.md b/accessibility-code-checker/cypress/README.md new file mode 100644 index 0000000..c79070b --- /dev/null +++ b/accessibility-code-checker/cypress/README.md @@ -0,0 +1,13 @@ +# Accessibility Code Checker - Cypress integration + +This workspace demonstrate how to integrate Siteimprove's Accessibility Code Checker with Playwright. + +## Setup + +See [the generic instructions](../README.md#setup) for setting up the project. + +## Cypress + +Cypress runs all of its tests in its own Javascript world, which makes things a bit harder to report on the finding (e.g., console logging should occur in the NodeJS world). This is done through the `cy.task()` call, but requires a bit of setup: +* The reporting capacities are defined in the [cypress.config.ts](./cypress.config.ts) file. This can be added to any existing Cypress configuration file. +* The tests are runs from the [test/cypress.spec.ts](./test/cypress.spec.ts) file. \ No newline at end of file diff --git a/accessibility-code-checker/cypress/test/cypress.spec.ts b/accessibility-code-checker/cypress/test/cypress.spec.ts index 1c40d21..6d32aed 100644 --- a/accessibility-code-checker/cypress/test/cypress.spec.ts +++ b/accessibility-code-checker/cypress/test/cypress.spec.ts @@ -11,6 +11,11 @@ it("should be accessible", () => { // TODO: Adapt with what is present in your own page cy.get(".testimonials-top").should("exist"); + /* + * Usual Cypress instructions can live here. + * For example, navigating through the page, opening menus or modals, etc. + */ + const audit = cy // Get the document from the page .document() diff --git a/accessibility-code-checker/playwright/README.md b/accessibility-code-checker/playwright/README.md new file mode 100644 index 0000000..0acdb58 --- /dev/null +++ b/accessibility-code-checker/playwright/README.md @@ -0,0 +1,11 @@ +# Accessibility Code Checker - Playwright integration + +This workspace demonstrate how to integrate Siteimprove's Accessibility Code Checker with Playwright. + +## Setup + +See [the generic instructions](../README.md#setup) for setting up the project. + +## Playwright + +All the code for checking the page reside in the [test/playwright.spec.ts](./test/playwright.spec.ts) file. \ No newline at end of file diff --git a/accessibility-code-checker/playwright/test/playwright.spec.ts b/accessibility-code-checker/playwright/test/playwright.spec.ts index dc5ab1c..384133b 100644 --- a/accessibility-code-checker/playwright/test/playwright.spec.ts +++ b/accessibility-code-checker/playwright/test/playwright.spec.ts @@ -12,6 +12,11 @@ test("is page accessible", async ({ page }) => { // Get the document handle from the page const document = await page.evaluateHandle(() => window.document); + /* + * Usual Playwright instructions can live here. + * For example, navigating through the page, opening menus or modals, etc. + */ + // Scrape the page const alfaPage = await Playwright.toPage(document);