This repository includes scripts to download all the necessary components for a developer to begin developing automated feature tests on their developer machine with the REDCap Cypress Test Framework.
- Software Prerequisites
- Developer Toolkit Installation Instructions
- Start REDCap Test Environment
- Configure & Start Cypress
- Contribute to Feature Tests
- Update Repositories
- Rebuild Docker Containers
- Configure Cypress REDCap version
- Create SSH Key
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
-
Visual Studio Code - optional. Recommended IDE.
-
Clone this repository to your machine.
git clone git@github.com:aldefouw/redcap_cypress_docker.git
-
Download Repositories
Execute download_repos.sh to download the repositories.
./download_repos.sh
This script also configures base settings for Cypress.
-
Download REDCap
Execute download_redcap.sh to download specific version of REDCap you need.
./download_redcap.sh
Follow onscreen prompts. This step requires credentials for REDCap Community site.
Start your REDCap Docker containers (PHP/Apache, MySQL, Mailhog).
cd redcap_docker
docker compose up
- Install Cypress & dependencies for REDCap Cypress Test Framework.
cd redcap_cypress
npm install
- Open Cypress.
npx cypress open
-
Create your own fork of redcap_rsvc that is based upon https://github.com/aldefouw/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 aldefouw/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
If you want to test against a new version of REDCap that you've downloaded, first Download REDCap.
Then change the following variable in redcap_cypress/cypress.env.json
to the specific version of REDCap you want to test:
"redcap_version": "13.1.37"
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
Generating a key is beyond the scope of what this documentation can cover.
Please consult GitHub's SSH documentation for more information: https://docs.github.com/en/authentication/connecting-to-github-with-ssh