Grant or Fix TestCafe Permissions on macOS

TestCafe includes an automation engine called “TestCafe Browser Tools”. This engine automates browsers and handles screen capture.

To function, the TestCafe Browser Tools binary requires high-level system privileges.

Due to security enhancements in macOS 10.15 Catalina, the process of obtaining system permissions has become more complicated. This article explains how to grant TestCafe the permissions it needs, and what to do when things go wrong.

• Grant system permissions to TestCafe (Clean Install)
• Fix System Permissions
• Potential Installation Conflicts
• Troubleshooting Tips

Grant system permissions to TestCafe (Clean Install)

Follow these instructions if you have a new installation of TestCafe.

Step 1. Run TestCafe

Launch TestCafe. If you don’t have a TestCafe test on hand, launch the sample test from the Getting Started tutorial.

testcafe all test.js

Since you haven’t granted any permissions to TestCafe, the test will fail, and the operating system will open the following dialog:

Step 2. Grant system-level permissions

1. Open the “Security and Privacy” pane of the “System Preferences” dialog.
2. Click the lock at the bottom left of the dialog. Log in when the system prompts you.
3. Select the “Screen Recording” item in the “Privacy” tab sidebar.
4. Click the “+” button to add a new entry.
5. Navigate to your home folder. Press "Cmd"+"Shift"+"." to view hidden files and folders.
6. Enter the .testcafe-browser-tools folder and select the TestCafe Browser Tools application.

Step 3. Grant browser-level permissions

By now, you should have already granted the necessary system-wide permissions to TestCafe. Launch a test to confirm that it doesn’t yield an error:

testcafe all test.js

Whenever you launch TestCafe in a new browser, the framework requests permission to automate that browser. Press “OK” to launch the test.

Fix System Permissions

Step 1. Reset Application Permissions

1. Execute the following shell command to reset screen recording permissions:

tccutil reset ScreenCapture com.devexpress.testcafe-browser-tools

2. Execute the following shell command to reset automation permissions:

tccutil reset AppleEvents com.devexpress.testcafe-browser-tools

Step 2. Run TestCafe

Launch TestCafe. If you don’t have a TestCafe test on hand, launch the sample test from the Getting Started tutorial.

testcafe all test.js

Since you just revoked all TestCafe permissions, the test will fail, and the operating system will open the following dialog:

Step 2. Restore system-level permissions

1. Open the “Security and Privacy” pane of the “System Preferences” dialog.
2. Click the lock at the bottom left of the dialog. Log in when the system prompts you.
3. Select the “Screen Recording” item in the “Privacy” tab sidebar.

4. Look at the list of applications with Screen Recording permissions. If the list includes a “TestCafe Browser Tools” entry, remove the old entry:

   • Select the “TestCafe Browser Tools” entry.

   • Press the “-“ button below the list to remove the entry.

     Warning

     If you only remove the checkmark next to the entry, you won’t be able to complete the tutorial.

5. Click the “+” button to add a new entry.

6. Navigate to your home folder. Press "Cmd"+"Shift"+"." to view hidden files and folders.
7. Enter the .testcafe-browser-tools folder and select the TestCafe Browser Tools application.

Step 3. Restore browser-level permissions

Launch a test to confirm that TestCafe doesn’t yield an error:

testcafe all test.js

Whenever you launch TestCafe in a new browser, the framework requests permission to automate that browser. Press “OK” in the permissions dialog:

Potential Installation Conflicts

It is common to have multiple Testcafe installations per machine, even if this is unintentional. For example, if you use TestCafe Studio alongside the open-source version of the framework, you have at least two different installations of TestCafe. Others may have a local installation of the framework inside their test suite project, but use a global installation in other cases.

If you run TestCafe 1.18 or up, the number of TestCafe instances on your machine does not matter. All installations of the framework share a single TestCafe Browser Tools binary. TestCafe stores this binary in the user’s Home directory, inside the hidden ~/.testcafe-browser-tools folder.

If you run an earlier version of the framework, update TestCafe before you troubleshoot system permissions.

npm i -g testcafe 

Read the TestCafe 2.0 migration guide for more information.

Troubleshooting Tips

• Do not uncheck the TestCafe Browser Tools entry when you reset system-level permissions. Remove the entry altogether.
• If you run a local version of TestCafe, and could not fix the permissions with the help of the tutorial, reinstall TestCafe from scratch:
  1. Uninstall the local testcafe package and remove it from your project’s dependencies:

         npm uninstall -D testcafe
     

  2. Uninstall the global testcafe package to avoid potential conflicts:

         npm uninstall -g testcafe
     

  3. Purge the node_modules folder of testcafe-related libraries:

         rm -rf ./node_modules/testcafe*
     

  4. Delete the global .testcafe-browser-tools folder if it exists:

         rm -rf ~/.testcafe-browser-tools
     

  5. Confirm that the uninstallation is successful:

         npm list testcafe # Should yield an empty list
     

         which testcafe # Should yield an error message
     

  6. Re-install the TestCafe package:

         npm i testcafe --save-dev
     

  7. Follow the instructions in the first part of this article.
• If you run a local version of TestCafe, your project should contain its own copy of the TestCafe Browser Tools binary. This binary is located in the node_modules/testcafe-browser-tools/bin/mac folder. If no other strategy helps, select that binary instead of the global binary when you grant system-level permissions to TestCafe. Thanks to @liront2 on GitHub for the tip!