XMA Portal

Table of Contents

• Prerequisites
• Local Development
• Testing

Additional documentation can be found in the docs/ directory of each package.

Prerequisites

• Install pnpm on your machine

• Install Docker on your machine

• Install global dependencies

  pnpm install -g @dotenvx/dotenvx tsx prisma firebase-tools concurrently

• Install local dependencies

  pnpm install

Setting up Environment variables

Firebase Service Account

This project uses firebase-admin to handle server side authentication. In order to develop locally you will need to set up a service account and provide the credentials locally.

1. Generate a new service account for the XMA QA project.
2. Download the file
3. Save it to secrets/firebase-service-account.json.

Firebase Config

This project uses the firebase API to handle authentication. In order to develop locally you will need to set up a firebase project and provide the credentials locally.

1. Navigate your project on the Firebase Console

2. Click on the gear icon next to "Project Overview" and select "Project Settings"

3. Copy the apiKey, and projectId values from the firebase config

4. Rename .env.local.example from the root directory as .env.local and fill in the values:

   FIREBASE_PROJECT_ID=<your_project_id>
   FIREBASE_API_KEY=<your_api_key>

Root Directory

In order to correctly handle data in the project we need to supply the absolute path to the root of the project.

1. Run the following command from the root directory of the project:

   pwd

2. Assign the output to the ROOT_DIRECTORY variable in your .env.local file:

   ROOT_DIR=</absolute/path/to/xma-portal>

Local Development

• The local website is available at localhost:3000
• The Firebase Auth Emulator is available at localhost:4000/auth
• Prisma Studio is available at localhost:5555
• The Redis Queue runs on localhost:6379 but does not have a UI
• The MySQL database runs on localhost:3306 but does not have a UI

Dev Mode

The dev script starts and seeds a local server with the source code. Note that the development server handles hot-reloading for when code changes are made though you may occasionally need to.

NODE_ENV	Portal	Transcode Worker	Firebase	Seeding?	Watch Mode?
development	source	source	Emulators	True	True

Test Mode

The start:test script first builds the source code for NODE_ENV=test. Then it starts and seeds a local server with that built code.

NODE_ENV	Portal	Transcode Worker	Firebase	Seeding?	Watch Mode?
test	built	built	Emulators	True	False

Production Mode

The start:prod script first builds the source code for NODE_ENV=production. Then it starts and seeds a local server with that built code.

NODE_ENV	Portal	Transcode Worker	Firebase	Seeding?	Watch Mode?
production	built	built	Emulators	True	False

Staging Mode

The docker-staging scripts builds a local instance of the application's Docker images and runs them in a local "staging" environment. This mode is most useful for ensuring the CI workflow will build the Docker images correctly and run the application as expected.

NODE_ENV	Portal	Transcode Worker	Firebase	Seeding?	Watch Mode?
staging	docker	docker	Emulators	False	False

Working With The Staging Environment

The staging environment is designed to mimic the production environment as closely as possible while still allowing for local data. It builds and runs the application's Docker images, which means that you can test the application using the exact image that will be deployed to production. However, it still connects to a local MySQL database, Redis queue, and and the Firebase Emulators.

A basic script is provided to seed the staging environment with fake data. Run it by:

1. Overriding the seed.bke.ts script with the staging version:

   docker cp packages/portal/scripts/seed.staging.ts xma-portal-staging-portal-1:app/scripts/seed.bke.ts

2. Running the seed script in the staging environment:

   [!TIP] You can run this directly from the container instead of the command line by using the Docker Desktop app

   docker exec -it xma-portal-staging-portal-1 pnpm run seed

Testing

Note

Testing scripts can only be run in the packages/portal directory currently.

This project uses Vitest for running unit and integration tests. It uses Cypress and Playwright for running end to end tests. Each test is run with a unique script that can be run individually. The project's Github Actions workflows utilize these tests on every pull request.

• cypress-run
• cypress-open
• vitest-run
• vitest-coverage
• vitest-watch
• playwright-open
• playwright-run

Cypress Parallelization

Cypress does not run tests in parallel without a subscription to Cypress Cloud. However, we can run tests in parallel by executing multiple scripts at once.

1. Move to the packages/portal directory

   cd packages/portal

2. Run the dev server in test mode

   pnpm run -w start:test

3. Run the following command in a separate terminal:

   concurrently \
     'pnpm exec cypress run --reporter min --spec cypress/e2e/file.cy.ts' \
     'pnpm exec cypress run --reporter min --spec cypress/e2e/individual.cy.ts' \
     'pnpm exec cypress run --reporter min --spec cypress/e2e/study.cy.ts'

Scripts

build

Recursively builds each package in the project.

clean

Cleans the project's dependencies, builds, caches, and other temporary files by running a custom bash script.

dev

Recursively runs each package's source code in parallel. See the Dev Mode section for more details.

Note

The predev script starts the docker containers needed for local development before running this script.

dev-hma

Runs the dev script with the REACT_APP_PORTAL environment variable set to hma.

dev-xma

Tip

The portal's .env file sets REACT_APP_PORTAL=xma so this is identical to the dev

Runs the dev script with the REACT_APP_PORTAL environment variable set to xma.

dev-zma

Runs the dev script with the REACT_APP_PORTAL environment variable set to zms.

docker

Runs the docker containers needed for local development. The containers will run in the background uninterrupted.

docker-down

Removes the application's docker containers. It stops and removes the containers from both the docker and docker-staging scripts.

docker-staging

Warning

The docker-down script must be run before this command as the ports conflict

Builds the docker images for each package and runs the containers needed for a local staging environment. See the Staging Mode section for more details.

format

Runs Prettier on the source code. See .prettierrc.cjs for the project's configuration.

It's recommended to install an editor plugin (e.g. prettier-vscode) to get auto-formatting on save.

lint

Lints the code using Eslint. See .eslintrc.cjs for the project's configuration.

reset

Caution

This script is only intended to be run in local environments. It will (intentionally) fail in production environments.

Runs the ORM's reset script to reset the application's MySQL database.

start

Caution

This script does not set the NODE_ENV environment variable and will therefore fail. The start:prod or start:test script should be used instead

Recursively builds and runs each package's source code in parallel.

Note

The prestart script builds the source code and starts the docker containers needed for local development before running this script.

start:prod

Sets NODE_ENV to production and recursively builds and runs each package's source code in parallel. See the Production Mode section for more details.

Note

The prestart:prod runs the base prestart script with NODE_ENV set to production.

start:test

Sets NODE_ENV to test and recursively builds and runs each package's source code in parallel. See the Test Mode section for more details.

Note

The prestart:test runs the base prestart script with NODE_ENV set to test.

typecheck

Type checks the code using Typescript. See tsconfig.json for the project's configuration.

test

Runs the project's static analysis tools and its entire test suite using a custom bash script.

Other Tools

madge

Madge is a useful tool for visualizing module dependencies. It can be installed via npm as a global dependency (pnpm i -g madge).

The following command generates a list of every file's dependencies:

madge --ts-config ./tsconfig.json --extensions ts,tsx app/

• --circular flag shows circular dependencies in the codebase
• --orphans flag shows modules not used anywhere in the codebase
• --image madge.png flag saves the outputs graph as an image

Tip

Madge is extremely useful for debugging issues that appear in the built code but not in development. The culprit is likely circular dependencies that Remix's build process does not catch.