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.

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

The vets-website build has two main functions:

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

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.

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)

• run once to pull the latest Drupal content and build the static HTML files
• need to run this again when adding new templates based on new Drupal entities

yarn watch:content

• watches for changes to liquid templates or CSS
• separated from yarn watch because of JS memory issues

yarn preview

• You can run this concurrently with yarn watch. It adds local routes needed to preview Drupal nodes (e.g. /preview?nodeId=XX).

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

"Templating" refers to the process of data representing website content being compiled into an HTML file.

After setup, the vagov-content repo should be a sibling repo to vets-website. vagov-content contains static content files in the form of Markdown (.md) in the vagov-content/pages directory. At the top of each Markdown file, there are declarations of key-value pairs referred to as "frontmatter", which are often used to define metadata about the page or to describe how the page should be processed during the HTML compilation.

The most common key in frontmatter is a layout property, which refers to a file in vets-website/src/site/layouts. For example, this layout property refers to this layout file in vets-website. The frontmatter of the .md file are passed to the layout file as the global scope.

---
layout: favorite-movies.html
movies:
  - Ace Ventura
  - Disney Cars
  - Toy Story
---

I love movies! Here are some of my recommendations.

<p>{{ contents }}</p>
<ul>
{% for movie in movies %}
  <li>{{ movie }}</li>
{% endfor %}
</ul>

<p>I love movies! Here are some of my recommendations.</p>
<ul>
  <li>Ace Ventura</li>
  <li>Disney Cars</li>
  <li>Toy Story</li>
</ul>

After setup, your project should have issued a network request to fetch data from the VA CMS, Drupal. To verify, the response JSON should be located at vets-website/.cache/localhost/drupal/pages.json. To refresh the content, run yarn build:content --pull-drupal. The vets-website/.cache directory will be emptied and a new network request will be issued.

The JSON file returned by the CMS will be parsed into separate pages during the vets-website compilation process. Consider opening the vets-website/.cache/localhost/drupal/pages.json file to explore the data structures.

{
  "entityBundle": "landing_page",
  "entityId": "79",
  "entityPublished": true,
  "title": "VA records",
  "entityUrl": {
    "breadcrumb": [
      {
        "url": {
          "path": "/",
          "routed": true
        },
        "text": "Home"
      },
      {
        "url": {
          "path": "",
          "routed": true
        },
        "text": "Records"
      }
    ],
    "path": "/records"
  },
  "fieldIntroText": "Access your VA records and documents online to more easily manage your benefits."
}

<h1>{{ title }}</h1>
<p>{{ fieldIntroText }}</p>

<title>VA records</title>
<p>Access your VA records and documents online to more easily manage your benefits.</p>

The implementation of the Liquid templating language used by our project is TinyLiquid. We highly recommend using TinyLiquid's README as your resource while writing a template, as there are small differences from Shopify's language spec.

CI will build both applications and content with the following:

yarn build

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

• E2E or browser tests primarily run in Cypress.
• Some older, existing tests run in Nightwatch, but those are deprecated.

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

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' },
};

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

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