VA.gov

Table of Contents

• What is this?
• Common commands
• Building vets-website
  • Building applications
  • Building static content
  • Building both together
• Working in GitHub Codespaces
• Running tests
  • Unit tests
  • End-to-end (E2E) / Browser tests
• Changing Virtual Agent backend URL
• Running a mock API for local development
• More commands
• Supported Browsers
• API Keys
• Additional Resources

What is this?

This is the front end repository for VA.gov. It contains application code used across the site.

There are several repositories that contain the code and content used to build VA.gov. If you're looking to get started running VA.gov locally, you should read the Getting Started documentation.

Common commands

Once you have the site set up locally, these are some common commands you might find useful:

Building vets-website

Building applications

vets-website uses Webpack to bundle application assets.

To build all applications, run the following:

yarn build

To build one or more applications, you can use the --entry option:

yarn build --entry=static-pages,auth

To recompile your application when you make changes, run:

yarn watch

You can also limit the applications Webpack builds with --env entry:

yarn watch --env entry=static-pages,auth

The entryname for your application can be found in its manifest.json file.

If you're developing a feature that requires the API, but can't or don't want to run it locally, you can specify --env api:

yarn watch --env api=https://dev-api.va.gov

You will need to disable CORS in your browser when using a non-local API. Here are some helpful links that explain how to do this:

• https://stackoverflow.com/questions/3102819/disable-same-origin-policy-in-chrome
• https://stackoverflow.com/questions/4556429/disabling-same-origin-policy-in-safari

Note: If you try to log on, ID.me will redirect you to the environment that the API is set up for. So in the above example, you'd be redirected back to dev.va.gov.

Building static content

Static pages are created from the content-build repository. See the building static content documentation.

Building both together

After building the applications, running yarn build in the ../content-build directory will build content using the generated app bundles from vets-website/build/localhost/generated. The full build can be seen in ../content-build/build/localhost.

Working in GitHub Codespaces

Read the Codespaces documentation for this repository.

Running tests

Unit tests

To run all unit tests, use:

yarn test:unit

If you want to run only one test file, you can provide the path to it:

yarn test:unit src/applications/path/to/test-file.unit.spec.js

To run all tests for a folder in src/applications, you can use app-folder:

yarn test:unit --app-folder hca

To run all tests in a directory, you can use a glob pattern:

yarn test:unit src/applications/path/to/tests/**/*.unit.spec.js*

To run tests with stack traces, pass log-level trace:

yarn test:unit --log-level trace

To run tests with coverage output, you can pass the coverage option:

yarn test:unit --coverage

For help with test runner usage, you can run:

yarn test:unit --help

End-to-end (E2E) / Browser tests

• E2E or browser tests run in Cypress.

Before running Cypress tests, first make sure that:

1. vets-website is served locally on port 3001
   • You can do this with yarn watch
2. vets-api is NOT running
   • Any required APIs will be mocked by the Cypress test that needs them.

To open the Cypress test runner UI and run any tests within it:

yarn cy:open

To run Cypress tests from the command line:

yarn cy:run

To run specific Cypress tests from the command line:

# Running one specific test.
yarn cy:run --spec "path/to/test-file.cypress.spec.js"

# Running multiple specific tests.
yarn cy:run --spec "path/to/test-a.cypress.spec.js,path/to/test-b.cypress.spec.js"

# Running tests that match a glob pattern.
yarn cy:run --spec "src/applications/my-app/tests/*"
yarn cy:run --spec "src/applications/my-app/tests/**/*"

# Running tests that match multiple glob patterns.
yarn cy:run --spec "src/applications/a/tests/**/*,src/applications/b/tests/**/*"

To run Cypress tests from the command line on a specific browser:

yarn cy:run --browser chrome
yarn cy:run --browser firefox

For other options with yarn cy:run, the same options for cypress run are applicable.

Changing Virtual Agent backend URL

If not already create a .env file in the root of the project and add the following while updating the URL

VIRTUAL_AGENT_BACKEND_URL=https://some.url.com

Running a mock API for local development

In separate terminal from your local dev server, run

yarn mock-api --responses path/to/responses.js

See the mocker-api usage documentation for how to use the responses.js.

If you need to log in, go to your browser dev tools console and enter localStorage.setItem('hasSession', true) and refresh the page. This will then trigger a /v0/user call, which will then get the mocked response of a logged-in user. (Assuming you've mocked that response, of course.)

Responses to common API requests, such as /v0/user and /v0/maintenance_windows, you can use src/platform/testing/local-dev-mock-api/common.js

const commonResponses = require('src/platform/testing/local-dev-mock-api/common');

module.exports = {
  ...commonResponses,
  'GET path/to/endpoint': { foo: 'bar' },
};

More commands

After a while, you may run into a less common task. We have a lot of commands for doing very specific things.

Supported Browsers

API Keys

In order to work with the Facility Locator locally, you will need a Mapbox API key with dev access. see this link for details on handling non public keys and tokens. You will need to access the paramater store within AWS Systems manager, and get the dev mapbox token from this location: /dsva-vagov/vets-website/dev/mapbox_token.

Create a .env file in the root of vets-website, and assign the above token to a variable called MAPBOX_TOKEN. The .env file should already be configured to work with dotenv for webpack. Ensure that the .env file is in .gitigore and take care not to expose this token in any public commits. See this link for instructions on requesting AWS access.

Additional Resources

1. Frontend developer documentation home
2. Manual and Automated 508 Testing
3. Using yarn Workspaces