The @guidepup/setup CLI enables automation for VoiceOver on macOS and NVDA on Windows.
# Set up machine once for screen reader automation
npx @guidepup/setup setup
# In project directory install Guidepup
npm install @guidepup/guidepup
# In project directory install required screen reader assets
npx @guidepup/setup installThe setup CLI command configures your operating system for screen reader automation and only needs to be run once per machine:
npx @guidepup/setup setupIf you are running the setup CLI command in CI/CD, it is recommended to add the --ci flag to prevent prompts for manual interaction:
npx @guidepup/setup setup --ciIf you are running this command locally you may need to take some manual steps to complete setup by following the manual VoiceOver setup documentation.
If updating the TCC.db is not possible (due to enabled System Integrity Protection) or not required for your macOS setup, you can skip database updates by using the --macos-ignore-tcc-db flag:
npx @guidepup/setup setup --macos-ignore-tcc-dbNote
If the necessary permissions have not been granted by other means, using this flag may result in your environment not being set up for reliable screen reader automation.
Warning
For system TCC.db updates you must first disable System Integrity Protection (SIP). This comes with serious security implications, so please first refer to the Apple documentation for more details before taking any action. Consider whether you are able to use alternative manual setup steps for configuration before exploring this option further.
SIP only needs to be disabled while the required changes are being made. Re-enable SIP once the setup CLI command has completed.
If you are encountering errors in CI for macOS you can pass a --macos-record flag to the command which will output a screen-recording of the setup to a ./recordings/ directory:
npx @guidepup/setup setup --ci --macos-recordEach version of Guidepup requires specific screen reader assets to execute correctly.
Install the default supported screen reader assets with one command from your project directory:
npx @guidepup/setup installThe install CLI command uses your project's installed @guidepup/guidepup version to determine which screen reader assets to install.
New Guidepup releases may update the required screen reader assets. If you update Guidepup, rerun the install CLI command to install the latest supported screen reader assets.
You can install a specific screen reader by providing additional arguments to the install CLI command:
# Install VoiceOver
npx @guidepup/setup install voiceover
# Install NVDA
npx @guidepup/setup install nvdaScreen reader options include:
voiceoveron macOS (default)nvdaon Windows (default)
By default Guidepup downloads screen reader assets into the operating system's standard cache directory:
~/.cache/guidepup/on Linux~/Library/Caches/guidepup/on macOS%USERPROFILE%\AppData\Local\guidepup\on Windows
You can override the default cache directory using an environment variable:
GUIDEPUP_SCREEN_READERS_PATH=$HOME/guidepup npx @guidepup/setup installGuidepup tracks which projects use each installed screen reader asset. When an asset is no longer referenced by any project, it is automatically removed the next time the install CLI command runs.
Guidepup screen readers are installed directly from GitHub release URLs. If you are using a proxy you can use an environment variable to define the proxy URL:
HTTPS_PROXY=https://192.0.2.1 npx @guidepup/setup installYou can install the CLI globally:
npm install -g @guidepup/setupAfter which you can access the CLI directly through the guidepup command:
guidepup setup
guidepup installCheck out some of the other Guidepup modules:
@guidepup/guidepup- Reliable automation for your screen reader a11y workflows through JavaScript supporting VoiceOver and NVDA.@guidepup/playwright- Seamless integration of Guidepup with Playwright.@guidepup/virtual-screen-reader- Reliable unit testing for your screen reader a11y workflows.@guidepup/jest- Jest matchers for reliable unit testing of your screen reader a11y workflows.