This project has been archived. The latest iteration of the application can be found at px-benefit-finder repo.

📄 Benefits Eligibility

The BEARS (Benefits Eligibility Awareness Resources) is an interactive tool that enables the public to learn about benefits available to them depending on their life experiences. BEARS aims to simplify the experience of finding and understanding life experience based benefits, in both English and Spanish.

Currently, the supported life experiences include death of a loved one, disability, and retirement. We plan to introduce additional life experiences over time, including financial hardship, becoming a parent, recovering from a disaster, and more.

Build Setup

# install dependencies
$ npm install

# serve with hot reload at localhost:3000
$ npm run dev

# build for production and launch server
$ npm run build
$ npm run start

# generate static project
$ npm run generate

# federalist build
$ npm run federalist

# federalist local build
$ npm run federalist:local

# specs
$ npm run test
$ npm run test:watch

# you may want to look at additional scripts available in the package.json

For detailed explanation on how things work, check out Nuxt.js docs.

Local development tips

1. You can enable console.log by copying .env.txt and renaming it to .env. This file is already ignored in .gitignore so you do not need to worry about committing this.
2. Use the provided pre-commit hooks. To install, see the documentation in this repo.
3. When switching branches, it may be necessary at times to run npm i to ensure you get matching npms for the branch. The best way is to stop npm run dev, install and then start npm run dev again.

Using Docker

If one does not wish to use / install the build requirements on their local system, an alternative would be to use Docker. Docker is a containerization tool that allows for fresh, repeatable builds on a clean system. The artifact from a Docker build is an "image"; when that image is run, it starts a "container."

Building with Docker

To build an image of the BEARS software, use the following command:

  cd "$(git rev-parse --show-toplevel)" \
  && bash build_docker_image.bash

This will create a Docker image named "bears" that may be run as a container later.

Running the BEARS Image

To run a container based on the BEARS Docker Image, the following command may be used:

docker run \
  --rm \
  --interactive \
  --tty \
  --publish 3000:3000 \
  bears

This will run the container in the foreground (replace the --interactive and --tty flags with --detach to have it run in the background). The --publish flag makes it so that connection attempts to the port BEARS runs on is accessible outside of the container (e.g., from a web browser on the local system).

When the container is running, one may use a web browser to interact with the BEARS application at:

• http://localhost:3000/

Using Vagrant when Docker isn't Available

For systems where Docker is not installed, a Vagrantfile is provided so that the Vagrant tool may be used to start a virtual machine (VM) that has Docker installed. Note: one may need to install virtualization platform such as Virtualbox.

Starting a Vagrant Virtual Machine

To start Vagrant, use the following command:

vagrant up

This will start the virtual machine in the background. This virtual machine will have the BEARS source code copied to it as a part of the provisioning steps performed by vagrant up.

• note: the source code installed on the virtual machine is a copy of what's on the local filesystem. Any changes made on the virtual machine are not reflected on the local filesystem; any changes made on the local filesystem are not reflected on the virtual machine.

Once the virtual machine is running, one may connect to it using this command:

vagrant ssh

Running this command is like using ssh to connect to a remote system. To close the connection, use exit or logout normally.

Once connected to the virtual machine, use the steps listed previously to build an image of the BEARS software and run it as a container.

docker build -t bears . \
&& docker run --rm -it -p 3000:3000 bears

Spell Checking in both English and Spanish Languages

cSpell is set to check /locales/ and /content/ folders for both English and Spanish languages. If there are any words that need to be considered always true, they need to be added to the word list in the cSpell.json file in the root of the directory.

cSpell action is currently set to work only in PRs into main and when there is a push on the branches that starts with content/**.

Pa11y testing locally

To implement the pa11y testing locally in a containerized environment, use the following command:

cd "$(git rev-parse --show-toplevel)" \
&& docker compose up

You may use the following command to close the running containers:

docker compose down

Cypress Test Automation

# To run cypress tests headlessly
$ npm run cy:run:chrome

# To open Cypress Test Runner and manually run tests
$ npm run cypress:open

Useful links

• https://nuxtjs.org/
• https://webpack.js.org/
• https://jestjs.io/
• https://federalistapp.18f.gov/
• https://federalist.18f.gov/documentation/

Github Actions

• Main Workflows - Builds, tests the BEARS site.
• Check Spelling - Uses cspell to install language libraries for spell check code.
• Code Scanning - Scans for code quality and security issues in the BEARS site and it's dependencies.
• Cypress - Allows to manually run e2e test on a branch.
• Megalinter - Verifies code consistency.
• OWASP - Cron job to scan our application for security coverage.
• Accessibility - Leverages pa11y to scan code for accessibility.
• SNYK - Alerts us to vulnerabilities in our dependencies.
• Unit Tests - Runs our unit tests in a node environment.
• Woke - Let's us run woke commands in our actions.
• Dependabot - Creates Pull Requests weekly for available dependency updates.

Federalist builds

• https://federalistapp.18f.gov/sites/983/builds

Design considerations

• Some items we only render client-side this is because the data relationships are not fully captured by Nuxt.js and by moving them client-side Vue.js is able to track those relationships.
• There are some integration issues between USWDS components and Vue.js. The current approach tries to use each framework by it's public API's as much as possible.