-
Notifications
You must be signed in to change notification settings - Fork 36
Pre Requisites to Using & Installing Framework
Please ensure that the following is true:
- Test Instance of REDCap accessible via HTTP
- Git installed on your host machine
- NodeJS installed on your host machine (dependency to install the Cypress environment)
- Sed (Stream Editor) & MySQL CLI binaries installed on host machine
Detailed descriptions follow.
To work with this framework, you'll need a running, local TEST instance of REDCap.
Please do NOT use your DEVELOPMENT instance of REDCap because this framework depends upon being able to setup and teardown your TEST database.
You may use any method you want to setup and configure a REDCap TEST instance.
However, the easiest way to get a TEST instance of REDCap is likely to spin up a DOCKER container on your local host machine.
You will need Docker running on your operating system in order to run Docker containers on your machine. Please download one of the following depending upon your system's operating system.
MacOSX
Docker for Mac is known to run on OSX >= 10.12.
https://download.docker.com/mac/stable/Docker.dmg
Windows
https://docs.docker.com/desktop/install/windows-install/
Note: Many of the Windows Docker installations require CPU virtualization flags (such as Vtx) to be enabled. This may necessitate changing BIOS configurations.
You will additionally need a Docker repository that contains a configuration file to setup and tear down your local TEST environment. Please download one of the following.
REDCap Docker
https://github.com/aldefouw/redcap_docker
A barebones Docker container that features tmpfs database configuration for fast testing.
After you download one of these repositories and make sure that the docker-compose.yml file settings are correct, you can issue the following command:
docker-compose up
This command will spin up the container(s) that are defined within the repository. Please note that if you'd like to daemonize your environment, you can issue a -d switch, as shown below:
docker-compose up -d
In order to contribute to the repository, please have a running local copy of Git installed.
https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
Git will allow you to contribute commits to the codebase. Although a Git tutorial is outside the scope of this documentation, learning Git is a useful skill for software developers and dev ops professionals alike.
If you are used to a GUI, you might consider downloading the GitHub Desktop application which is a visual companion for Git.
Download GitHub Desktop for Mac
Download GitHub Desktop for Windows
The Cypress environment is installed using the NPM package manager. You will need NodeJS installed on your machine in order to install all of the Cypress dependencies.
Although there are several ways to download NodeJS through various package managers (which you are welcome to use if you prefer), below is a link to the standard installation method:
https://nodejs.org/en/download/
Sed is used for Regular Expression matching against your database and is heavily involved in the database seeding process.
MySQL CLI is used to import the SQL files into your TEST database.
Both MySQL CLI & Sed need to be installed and available in your $PATH in order for the REDCap Cypress Test Framework to function correctly.
If you have a non-standard path for MySQL (or MySQL CLI isn't part of your system $PATH), you can point the REDCap Cypress test framework to your MySQL CLI binary by configuring the following object in cypress.env.json:
{ "mysql" : { path: "path/to/alternative/mysql/cli/here" } }
You can also use your Docker container's MySQL CLI. The example assumes you are using the redcap_docker - https://github.com/aldefouw/redcap_docker - repository.
For example, assume your MySQL CLI path provided is the following:
"mysql": {
"host": "db",
"path": "docker exec -i $(docker ps -f 'name=app' --format "{{.Names}}") mysql",
"port": "3306",
"db_name": "redcap",
"db_user": "root",
"db_pass": "root"
}
Since the stability of Docker container names can be low, we highly recommend simply installing MySQL CLI on your host machine instead so that you can simply point to the MySQL path and be done with it.
MacOSX typically has MySQL CLI binaries available by default. If not, you can use a package manager such a Homebrew to install them.
For Windows Machines, you can use the Docker MySQL CLI using the example command path listed above docker exec -i db_container_name mysql. If you'd prefer to use a native version of the CLI, it's recommended that you use the Chocolatey package manager to download and install MySQL CLI.
Please note that these binaries also need to be available in your OS environment $PATH.
If you have completed installing / configuring all of the pre-requisites, please proceed to Installing the Cypress Framework.