Skip to main content

Environment Setup

This guide applies to users of the @guidepup/guidepup or @guidepup/playwright packages.

OS environment set up is not required for users of the @guidepup/virtual-screen-reader package.

Automated Setup​

For some operating systems, enabling control of screen readers is tightly controlled.

To make environment setup easier @guidepup/setup was created to handle the setup of your OS for you. Run the setup with:

npx @guidepup/setup

The CLI will first attempt to configure your environment itself, but on systems with tighter security controls such as MacOS with System Integrity Protection (SIP), it may prompt you for additional inputs such as username and password so that it can complete the setup through UI automation.

If you are uncomfortable with providing credentials to this CLI you can manually achieve these steps by following the Manual VoiceOver Setup guide.

⚠️ Warning

You might be tempted to disable System Integrity Protection (SIP) to streamline this process, but this comes with serious security implications so please first refer to the Apple documentation for more details before taking any action.

It is strongly advised that you use @guidepup/setup or the Manual VoiceOver Setup guide for local development in preference to changing SIP status.

Recording Setup (MacOS Only)​

If you are encountering errors in CI for MacOS you can pass a --record flag to the command which will output a screen-recording of the setup to a ./recordings/ folder within the current working directory.

npx @guidepup/setup --record

GitHub Action​

Add this guidepup/setup-action step to enable screen reader test automation in GitHub CI:

- name: Guidepup Setup
  uses: guidepup/setup-action

Issues​

If you are encountering issues with @guidepup/setup then please reach out and raise a GitHub issue.