IGVF-DACC/igvf-ui

The Next.js-based UI portion of IGVF-DACC that works with igvfd

This is the UI portion of the IGVF DACC project bootstrapped with Next.js. This relies on the igvfd project to supply its data.

Getting Started

You must first install Docker Desktop and launch it so that its window with the blue title bar appears. Keep this app running in the background while you test igvf-ui locally.

1. Clone the igvfd repo and start its server:

# In igvfd repo.
$ docker compose up --build

2. Clone this repo (igvf-ui) and start the Next.js server:

# In igvf-ui repo.
# Note the build flag is only required if dependencies (e.g. package.json) have changed.
# igvf-ui branches change dependency versions frequently, so it makes sense to use the build flag
# whenever you switch between igvf-ui branches, or the dev branch gets new branches merged in.
$ docker compose up --build

Open http://localhost:3000 with your browser to see the igvf-ui home page.

Changes you make to Javascript files hot reload this local igvf-ui.

When you have finished local development, stop and clean up the Docker instances in both terminals:

$ docker compose down -v

The Docker Desktop app should now show no running containers.

Signing Onto the Site

If you want to sign into the site you need to:

1. Download the environment-variable files and place them in the igvf-ui root directory.
2. Make sure you have a user record in the igvfd user.json test insert file.

You can download the environment files here:

https://drive.google.com/drive/folders/1jBPTau0Bqzr418IjraWnEhFgiy09e_98?usp=sharing

Move these both to your igvf-ui root directory, then rename the dot-env.local file to .env.local.

You need to make sure you have a user record in the user.json test insert file. When you click “Sign In” on the site, you can enter your username and password in the login text fields. If you have a Stanford email, you can use single-click sign in with the Google button.

Installing Packages

Install packages from the Docker environment itself (to ensure proper npm version and package.json format).

For example to install uuid package start interactive container:

$ docker compose -f docker-compose.test.yml run nextjs /bin/sh

In container run desired npm install command:

$ npm install uuid

Changes should be reflected in the package*.json files of local repository (exit container and commit them to git). Make sure to use docker compose up --build when starting the application the next time to rebuild Docker image with latest dependencies.

Testing

Jest Tests

Use Jest for unit testing individual functions and isolated React components that rely on simple data. More complex React components, e.g. those relying on server data, typically get tested better with Cypress.

To execute all Jest tests and clean up:

$ docker compose -f docker-compose.test.yml up --exit-code-from nextjs
....
$ docker compose -f docker-compose.test.yml down -v

Or run tests interactively:

# Start interactive container.
$ docker compose -f docker-compose.test.yml run nextjs /bin/sh
# In interactive container (modify test command as needed).
$ npm test
# Run specific Jest test (e.g. separated-list).
$ npm test -- separated-list

And stop and clean, exit the interactive container and then:

$ docker compose down -v

Writing Jest Tests

This project uses the React Testing Library (RTL). Next.js provides a primer on creating your own Jest tests. You need to use RTL queries to extract portions of the DOM to test. You then need a combination of the Jest matchers and RTL matchers to perform the tests.

Jest tests use the coveralls code coverage service. We must strive to get 100% code coverage with Jest tests, or make separate tickets to get to 100% coverage if doing so in a primary ticket would cause too much code review churn.

Excluding Files From Coveralls

In extremely rare cases, some Javascript files might not make sense to write Jest tests for. In this case, you can exclude the file from coveralls coverage by including the following comment after the import lines:

/* istanbul ignore file */

Cypress Tests

Use Cypress for end-to-end integration testing, such as testing entire pages, interacting with those pages as a user would, and testing navigation between pages.

Run Cypress tests with Docker Compose.

1. Start igvfd:

# In igvfd repo. Note can use -d flag to detach from output.
$ docker compose up

2. Start igvfd-ui:

# In igvf-ui repo.
$ docker compose up

3. Run Cypress tests:

# In igvf-ui repo.
$ docker compose -f docker-compose.cypress-m1.yml up --exit-code-from cypress

Note if you want to run Cypress locally using the official Cypress image (not for M1 macs) you can use the docker-compose.cypress-on-circle.yml in ./docker/cypress folder, e.g.:

# In igvf-ui repo.
# Temporarily copy yml to root directory so Docker context is correct.
$ cp ./docker/cypress/docker-compose.cypress-on-circle.yml docker-compose.cypress.yml
# Run tests.
$ docker compose -f docker-compose.cypress.yml up --exit-code-from cypress
# Clean up untracked yml.
$ rm docker-compose.cypress.yml

4. Review video in ./cypress/videos/.

5. Stop and clean up igvf-ui and igvfd services in respective terminals:

$ docker compose down -v

Writing Cypress Tests

Generally, each page or major feature on a page should have its own Cypress test, though some pages might have too few elements to justify this. This Cypress tutorial provides a good starting point for writing these tests, which in many ways shares methods with Jest tests.

Editor Setup

Visual Studio Code

1. Install Visual Studio Code if needed.
2. Install the ESLint extension so you can see code-formatting errors.
3. Install the Prettier extension. This automatically formats the code to standard on each save.
4. Install the Tailwind CSS IntelliSense extension. This lets you see and select Tailwind CSS classes as you type them, and shows the corresponding CSS when you hover over Tailwind CSS classes.

In addition, you might have a better experience if you set these in your Visual Studio Code JSON settings, either as your preferences (user settings) or specific to the igvf-ui project (workspace settings):

  "css.validate": false,
  "editor.quickSuggestions": {
    "strings": true
  },
  "editor.tabSize": 2,
  "emmet.includeLanguages": {
    "javascript": "javascriptreact"
  },
  "prettier.configPath": "./prettier.config.js",
  "prettier.useEditorConfig": false,
  "tailwindCSS.classAttributes": ["class", "className"],
  "tailwindCSS.emmetCompletions": true,
  "tailwindCSS.includeLanguages": {
    "javascript": "javascript",
    "html": "HTML"
  },

Some of these might already exist in your settings, so search for them first to avoid conflicts.

Automatic linting

This repo includes configuration for pre-commit hooks. To use pre-commit, install pre-commit, and activate the hooks:

pip install pre-commit==2.17.0
pre-commit install

Now every time you run git commit the automatic checks are run to check the changes you made.