The REDCap Cypress Developer Toolkit provides an automated framework for validating REDCap’s core functionality. Automated testing helps ensure system integrity, reduces manual testing burden, and supports institutions in meeting regulatory compliance requirements (e.g., 21 CFR Part 11).
The toolkit was the brain child of Adam De Fouw, who deserves most of the credit for getting it off the ground. This and all related projects were originally developed by him and the RSVC Automated Testing Subcommittee (ATS). They are now maintained by Vanderbilt University Medical Center (VUMC). RSVC continues to contribute to updates and actively uses the toolkit for REDCap validation efforts.
This repository includes scripts to download all the necessary components for a developer to begin developing automated feature tests on their developer machine. This toolkit is based on the industry-standard Cypress Testing Framework.
If you'd like to participate in our ongoing automation efforts, see our Contribution Guidelines.
Automated testing involves executing pre-scripted tests against a REDCap instance to validate that core functionality works as expected. These tests:
- Ensure system stability after software updates
- Reduce redundant manual testing for common workflows
- Support regulatory compliance efforts by providing structured validation
Tests are executed in a controlled test environment and should never be run on a production system, as they modify project data.
Not all REDCap features are suitable for automation. When determining which features should be tested automatically, the RSVC considers:
- Reproducibility – Can the test be executed consistently across institutions?
- Regulatory Impact – Does the feature support compliance with 21 CFR Part 11?
- Complexity – Is automation feasible, or does the feature require manual review?
- Test Stability – Does the test produce reliable results across different REDCap versions?
For each REDCap release, RSVC reviews system changes and determines which features should be tested manually and which can be automated.
- Software Prerequisites
- Create SSH Key
- Developer Toolkit Installation Instructions
- Changing REDCap Versions
- Start REDCap Test Environment
- Configure & Start Cypress
- Contribute to Feature Tests
- Update Repositories
- Rebuild Docker Containers
The following steps are intended to help set up a testing environment on a personal computer in order to aid with development and contribute changes back to this project. If instead you're hoping to re-run all automated tests at your institution, see Creating An Automated Testing Environment.
A developer needs the following software on their machine before installing this Developer Toolkit.
-
Git (version control)
- for Windows
- for macOS options (choose one)
- for Linux
-
Docker Desktop - available for Windows, macOS, Linux
-
Node.js - available for Windows, macOS, Linux
-
VS Code - This is the recommended IDE, but others may be used as well (e.g. PhpStorm). Be mindful that Visual Studio Code is most often referred to as VS Code in part to distinguish it from a different application simply called Visual Studio which we do not use.
You will need to place your public key on GitHub for this process to work correctly.
To generate a key on your local machine, most of time the command is:
ssh-keygen
Please consult GitHub's SSH documentation for more information: GitHub SSH Key Instructions
Specifically, you will need to
-
Clone this repository to your machine. 1
git clone git@github.com:vanderbilt-redcap/redcap_cypress_docker.git -
Download Repositories
Execute download_repos.sh to download the repositories. 2
cd redcap_cypress_docker ./download_repos.shThis script also configures base settings for Cypress.
To test against a different version of REDCap, simply run ./download_redcap.sh again and specify the desired version.
Run the following from the command line to start the test environment. You will be prompted for REDCap Community site credentials in order to download REDCap the first time you run this and after certain updates.
./run.sh
The following should be run periodically to ensure your local environment includes the latest changes.
./update.sh
The following videos have been deprecated since the steps have been modified & simplified significantly since they were created. We keep them for reference:
-
Create your own fork of redcap_rsvc that is based upon https://github.com/vanderbilt-redcap/redcap_rsvc
-
Configure the cloned redcap_rsvc repository as needed to match your own Fork.
cd redcap_cypress/redcap_rsvc
git remote rename origin upstream
git remote add origin <your_fork_url_here>
Having your own fork enables you to issue pull requests to vanderbilt-redcap/redcap_rsvc after you complete a feature.
Execute ./update_repos.sh from this repository.
./update_repos.sh
This will resync your Developer Toolkit to the latest versions.
Caution: Only do this if you understand what the implications of updating submodules are.
If changes are made to the Docker images, you will need to rebuild your containers before spooling them up.
docker compose build
Footnotes
-
Git Clone Fail: If the message says you do not have permissions or mentions a public key, you might need to setup a SSH key with Github. ↩
-
Shell Script not Running: If you are on Windows and you see no outputs, you will need to run in a Bash shell. Because you have Git, you might have Git Bash installed. At the top of your VS Code terminal, on the right, Click on the down-arrow next to the plus sign and select Git Bash. ↩