Skip to content

Latest commit

 

History

History
190 lines (125 loc) · 8.01 KB

building-web.md

File metadata and controls

190 lines (125 loc) · 8.01 KB
Raw

Building Accessibility Insights for Web

This document describes how to build and test Accessibility Insights for Web (the browser extension).

Prerequisites

Tools

You will need the following tools installed:

  • Node ^16.14.2 (check by running node --version) - This is the version being enforced on our builds
  • Yarn >= 1.22.10 (check by running yarn --version)
    • Note: There is a known name collision between Yarn package manager and Hadoop YARN. If you have Hadoop YARN installed, replace yarn with yarnpkg in the commands below.
  • macOS only Xcode. This is needed when installing certain dependencies with native compilation steps. After installing Xcode, run the following commands from a command terminal:
    xcode-select --install
    sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
    sudo xcodebuild -license accept

We recommend VS Code for editing/debugging, but you can use whichever editor you prefer. The extensions we recommend should be automatically suggested to you when opening this repository's folder in VS Code.

Fork and clone the repository

See Git branch setup.

Install packages

yarn install

Building

# One-time build
yarn build

# Build with type-checking
yarn tbuild

# Continuously rebuilds as you modify non-test files
yarn watch:build:web

IDEs/Editors like VSCode will run the TypeScript compiler in the background providing information about type-errors in those contexts; tbuild is useful when not developing in those environments.

Running Locally

  • Build the (unpacked) extension

    yarn build

  • Add the extension to your browser

    • Click on the 3-dotted-menu in the upper right corner and then select "More Tools" and then "Extensions"

    • Verify that developer mode is enabled in the upper right

    • Click on the Load unpacked button

    • Choose the following directory

      ./drop/extension/dev/product/ - bundled like a production release

    IMPORTANT: Ensure that you are testing locally before pushing a change.

  • Look for the Dev Logo extension icon to the right of the address bar

  • (Optional) run yarn react-devtools:setup && yarn react-devtools to open a standalone React DevTools instance that will automatically connect to any open popup or detailsView pages from a dev build of the extension.

Testing

We use Jest as our test framework, along with typemoq and react-testing-library. We make liberal use of Snapshot Testing for unit tests of React components.

Unit Tests

We expect almost all code to be covered by unit tests (the main exception to this rule are "initializer" entry points that set up dependency graphs). Almost all Pull Requests should include at least some new unit tests.

# This runs only unit tests changed in your feature branch
# Run this regularly during feature development
yarn test --changedSince main

# Test only files matching a particular name pattern
yarn test -- SomeFile.test.tsx

# This runs unit tests continuously as they are updated
yarn watch:test

# This runs *all* unit tests; usually unnecessary, PR builds will do this
yarn test

# -u updates snapshots
yarn test --changedSince main -u
yarn test -u
yarn test -u -- SomeFile.test.tsx

Extra command line arguments and flags are passed along to Jest. See more about Jest options here.

To debug using an external tool, run node --inspect-brk ./node_modules/jest/bin/jest.js --projects src/tests/unit --runInBand -- {RELATIVE_FILE_PATH}. In Chrome, for example, navigate to chrome://inspect and click Open dedicated DevTools for Node.

End-to-End Tests

We expect most features to have at least one major scenario covered by an end to end test, but most individual Pull Requests won't require new end-to-end tests.

We use Playwright for browser automation in our end-to-end UI tests. There are some known limitations:

  • You must use a non-admin prompt to avoid this issue.
  • Headless Chromium does not support browser extensions, so our E2E tests require the ability to run a non-headless Chromium process. Because of this, they are incompatible with non-graphical development environments (notably, a default WSL environment on Windows). For an example of emulating a graphical environment using xvfb, see ./Dockerfile. For details, see issue #853.

To run the E2E tests locally:

yarn test:e2e

# -u updates snapshots
yarn test:e2e -u

# Run from the context of the docker container our Linux CI builds use (requires Docker to be installed)
yarn test:e2e:docker

# Run tests for the report package
yarn test:report:e2e

# -u updates snapshots for the report package
# Windows: 
yarn test:report:e2e -u
#Linux and Mac:
yarn test:report:e2e -u

# On occasion you may need to clear the Jest cache before running tests
yarn jest --clearCache

Generally, if a Pull Request doesn't touch any E2E tests, you don't have to run them yourself; the automated Pull Request build will do it for you.

Commands to run before check in

  • You should run a FastPass (formatting and lint checks) before creating a Pull Request to main:

    yarn fastpass

  • If this catches formatting or linting issues, you can fix them with a combination of:

    yarn fastpass:fix

# or, in individual steps:
yarn lint:fix
yarn format:fix
yarn copyright:fix

  • We normally don't run the full end to end test suite before sending a Pull Request (we let the build agents do that), but if you are working on a change where you are particularly concerned about breaking end to end tests, you can run all of our Pull Request checks with:

    yarn assessment

Using VS Code

To run a task from the command palette, press Ctrl + Shift + P, select Tasks: Run Task, and select the task you want to run:

  • Test current file in VSCode runs just the tests in the currently-opened test file

To debug a test inside VS Code, set a breakpoint and click the debug button or press F5.

To attach VS Code as a debugger to a separate instance of Chrome, make sure you've launched Chrome with the --remote-debugging-port=9230 command line argument, and then use either of the Attach debugger... debug profiles from the VS Code Debug pane.

To debug using an external tool, run the Debug current test file outside VS Code task. In Chrome, for example, navigate to chrome://inspect and click Open dedicated DevTools for Node.

You can start an interactive watch session that automatically runs tests affected by uncommitted changes. To do this, run Begin Jest watch session from the command palette.

Self-FastPass

Accessibility Insights for Web supports running some of its own FastPass checks against itself. To do so, open the F12 browser developer tools console from the context of the "DetailsView", "Popup", or "Insights" pages, and run:

  • window.selfFastPass.automatedChecks()
  • window.selfFastPass.needsReview()

You can also use window.selfFastPass.customScan(['axe-rule-id']) to scan with a specific set of rules. This is mostly used to run self-tests of various assessment requirements. For example, to see all the elements our Custom Widgets requirements would pick up, you could use window.selfFastPass.customScan(['custom-widget']).