snowdensb / vets-website

Frontend for VA.gov
Creative Commons Zero v1.0 Universal
0 stars 0 forks source link

VA.gov Build Status

What is this?

This is the front end repository for VA.gov. It contains application code and templates 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:

I want to... Then you should...
fetch all dependencies yarn install; run this any time package.json changes
build both static HTML pages and applications yarn build
run the webpack dev server yarn watch

Building vets-website

The vets-website build has two main functions:

  1. Build the application assets (JS, CSS)
  2. Create the static HTML pages

Building applications

vets-website uses Webpack to bundle application assets.

To build all applications, run the following:

yarn build:webpack

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

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

VA.gov contains many pages that include content generated from a Drupal-based content model. When testing changes to static pages, or to see what your application looks like on VA.gov, you'll need to build these static pages using the following commands:

yarn build (add —pull-drupal to get the latest content from production - needs active socks proxy connection)

yarn watch:content

yarn preview

If you do not have access to the SOCKS proxy, you can fetch the latest cached version of the content with the following:

yarn fetch-drupal-cache

Building both together

CI will build both applications and content with the following:

yarn build

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 some extra debugging info, you can pass a log-level:

yarn test:unit --log-level debug

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

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 --headless --browser chrome
yarn cy:run --headless --browser firefox

# Without --headless, the test runner will open and run the test.
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.

To run Nightwatch tests, you first need three things:

  1. Install the Java JDK on MacOS (if needed):
    brew update
    brew tap adoptopenjdk/openjdk
    brew cask install adoptopenjdk8
  2. vets-website served locally on port 3001
    • You can do this with yarn watch
  3. vets-api to NOT be running
    • The browser tests will use a simple mock api on port 3000, but only if nothing is already attached to that port
yarn test:e2e

Just like with unit tests, you can also specify the path to the test file

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

Contract tests

To run all contract tests locally:

yarn test:contract

To run a specific contract test:

BUILDTYPE=localhost yarn test:unit src/applications/my-app/tests/example.pact.spec.js

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.

I want to... Then you should...
build the production site (dev features disabled). NODE_ENV=production yarn build --env.buildtype vagovprod --env.scaffold
fetch the latest content cache from S3 yarn fetch-drupal-cache (does not require SOCKS proxy access)
reset local environment (clean out node modules, Babel cache, and runs npm install) yarn reset:env
run only the app pages on the site for local development without building content. yarn watch --env.scaffold
run the site for local development with automatic rebuilding of Javascript and sass with css sourcemaps yarn watch:css-sourcemaps then visit http://localhost:3001/. You may also set --env.buildtype and NODE_ENV though setting NODE_ENV to production will make incremental builds slow.
run the site for local development with automatic rebuilding of code and styles for specific apps yarn watch --env.entry disability-benefits,static-pages. Valid application names are in each app's manifest.json under entryName
run the site for local development with automatic rebuilding of code and styles for static content yarn watch:static
run the site so that devices on your local network can access it yarn watch --host 0.0.0.0 --public 198.162.x.x:3001 Note that we use CORS to limit what hosts can access different APIs, so accessing with a 192.168.x.x address may run into problems
run all unit tests and watch yarn test:watch
run only e2e tests Make sure the site is running locally (yarn watch) and run the tests with yarn test:e2e
run e2e tests in headless mode yarn test:e2e:headless
run all linters yarn lint
run only javascript linter yarn lint:js
run only sass linter yarn lint:sass
run lint on JS and fix anything that changed yarn lint:js:changed:fix
run automated accessibility tests yarn build && yarn test:accessibility
run visual regression testing Start the site. Generate your baseline image set using yarn test:visual:baseline. Make your changes. Then run yarn test:visual.
test for broken links Build the site. Broken Link Checking is done via a Metalsmith plugin during build. Note that it only runs on build not watch.
add new npm modules yarn add my-module. Use the --dev flag for modules that are build or test related.
get the latest json schema yarn update:schema. This updates our vets-json-schema vets-json-schema https://github.com/department-of-veterans-affairs/ to the most recent commit.
check test coverage yarn test:coverage
run bundle analyzer on our production JS bundles yarn build-analyze
generate a stats file for analysis by bundle analyzer NODE_ENV=production yarn build:webpack --env.buildtype=vagovprod --env.analyzer. Note that if you get an error like FetchError: request to http://prod.cms.va.gov/graphql failed you need to be on the SOCKS proxy
load the analyzer tool on a stats file yarn analyze
add a new React app yarn new:app (make sure you have vagov-content sibling to vets-website)

Supported Browsers

Browser Minimum version Note
Internet Explorer 11
Microsoft Edge 13
Safari / iOS Safari 9
Chrome / Android Web view 44 Latest version with >0.5% of traffic
Firefox 52 Latest version with >0.5% of traffic

Additional Resources

  1. VA.gov Knowledge Hub
  2. Docs Directory
  3. Manual and Automated 508 Testing