HMDA Frontend Projects

The HDMA Frontend monorepo hosts the public facing applications for the collection, publication, and navigation of millions of HMDA records per year. This repository combines six, previously separate, React application repos in order to simplify component sharing, synchronize versioning of common dependencies, and improve rendering efficiency when navigating between apps.

Contents

• HMDA Frontend Projects
  • Contents
  • Technical Overview
  • Applications
    • HMDA Homepage
    • HMDA Filing
    • HMDA Data Browser
    • HMDA Platform Tools
    • HMDA Documentation
    • HMDA Data Publication
  • Development
    • Requirements
    • Installation
    • Running Locally
      • Integrating with the Filing application
        • Create Institutions
        • Bypass API Authentication
        • Configure the UI
    • Running via Docker
  • Testing
    • Unit Tests
    • End-to-End Testing
    • Running in TravisCI

Technical Overview

Each React application lives in it's own sub-directory of the /src folder, with shared assets and components housed in /common. All sub-applications are rendered as asynchronous components within an application shell /App.jsx that provides a common header. This approach eliminates unneccesary reloading of the site-wide navigation, giving the separate apps a more connected feel. React Router is used for client side routing with React Redux integrated for state management of the more complex apps, such as Filing. Unit tests are developed using Enzyme and end-to-end testing performed with Cypress. Dependencies are managed with yarn.

Applications

HMDA Homepage

HMDA Homepage is a single-page app providing easy access to the HMDA applications, tools, data products, and documentation.

HMDA Filing

The HMDA Filing Platform UI allows lending institutions to submit HMDA records, resolve errors, verify edits, review submission status and history, and sign submissions.

HMDA Data Browser

The HMDA Data Browser enables users to easily filter and download aggregated HMDA datasets.

HMDA Platform Tools

The HMDA Platform Tools assist filers in the preparation of submission data, including calculation of Rate Spread, generation and validation of Check Digits, as well as submission file generation and format verification.

HMDA Documentation

The HMDA Documentation site provides product FAQs, detailed Filing instructions, data publication schema and usage guides, as well as direction for using the HMDA Tools. Documentation content is hosted as easily editable Markdown files, loaded on-demand with the Fetch API, and rendered dynamically using the markdown-to-jsx library. This allows updates to be pushed to Production without a project redeployment.

HMDA Data Publication

HMDA Data Publication provides datasets and reports of HMDA data collected in or after 2017 which, combined with Census demographic data, can be used for data analysis purposes.

Development

Requirements

• Node >= v12.4.1
• Yarn

Installation

• Clone repo
• Run yarn from repo root to install depencencies

Running Locally

Several components of the Frontend (ex. Filing, Data Browser) require a connection to the HMDA Platform in order to operate. You can find instructions for the running the HMDA Platform locally here.

HMDA Help requires a connection to the HMDA Institutions API in order to operate. You can find instructions for the running the HMDA Institutions API locally in the README. Note that having the HMDA Platform running is a pre-requisite to starting the HDMA Institutions API.

If your development does not require this integration, yarn start will run the development server, opening a browser window to http://localhost:3000.

Integrating with the Filing application

By default, the locally running Frontend is configured to use the Filing API from the locally running Platform. In order to go through the Filing process, there are a few elements that need to be completed first:

• Create Institutions (Platform)
• Bypass API authentication (Platform)
• Configure the UI (Frontend)

Create Institutions

Before you can submit a Filing you need to have an Institution created on the Platform for each year you want to test. The following command will generate the required data for the default test Institution, for all currently available filing periods. You need to have the HMDA Platform started before running this command:

yarn ci-data

To create data for an Institution other than the default FRONTENDTESTBANK9999, you can modify cypress/ci/config/institutions.json and rerun the above command.

This Institution loading needs to be done each time the HMDA Platform is restarted.

Bypass API Authentication

On the Platform, you will need to set an environment variable to prevent the API from requiring an authentication token for incoming requests. If already running, you will need to restart the Platform.

export HMDA_RUNTIME_MODE=dev

Configure the UI

If you will be testing against an Institution that is not the default, you can configure this via a REACT_APP_* variable:

REACT_APP_LEIS=INSTITUTION1,INSTITUTION2

Second, you will need to bypass Frontend authentication. This is most easily done by running the Frontend the way we do in a Continuous Integration environment:

yarn ci

To combine these configuration options

REACT_APP_LEIS=INSTITUTION1,INSTITUTION2 yarn ci

You can now visit the filing application at http://localhost:3000/filing.

Running via Docker

To see the application running in a container you can run:

docker build -t hmda/hmda-frontend .
docker run -p 8080:8080 hmda/hmda-frontend

To build using docker-compose:

docker-compose build

Testing

Unit Tests

yarn test

Enzyme enables isolated testing of React components. Unit tests providing verification of feature implementation while also serving as suite of regression tests.

End-to-End Testing

yarn run cypress run

Cypress is used to perform end-to-end testing of the filing application, tools, data publication products, and data browser. It mimicks a user's interaction with the site and allows for rapid, automated system validation of project deployments.

Running in TravisCI

TravisCI is configured to automatically build and test each pull request to the Frontend repo. This includes running the HMDA Platform within the TravisCI virtual machine to enable testing of the Filing application. All mandatory environment variables are configured in the .travis.yml file.

Generation of video recordings is disabled by default using TravisCI environment variables.

CONFIG="--config video=false"

In the event that you need to review video to help debug CI failures, update the environment configuration as follows. This will save the video output to the Cypress Dashboard.

CONFIG="--config video=true"
RECORD="--record"
CYPRESS_RECORD_KEY=<Configured in TravisCI>