wyattades / boostid

Command suite for Pantheon website development and testing

Boostid

Command suite for Pantheon website development and testing

** THIS PACKAGE IS NOT YET READY FOR PRODUCTION **

Installation

• Install Boostid globally

  npm install -g wyattades/boostid

• It's helpful to have Docker v18 and up

  docker -v

Getting started

1. Setup dev environment for an existing Pantheon site, where <sitename> is the site's Pantheon name

   boostid setup -s <sitename>

   This walks the user through the following:
   • Authenticate with APIs: CircleCI, AWS, Terminus, Slack (this only needs to be done once)
   • Clones Pantheon site into folder under the current directory
   • Setup a multidev for automated upstream updates
   • Add Boostid config and testing files to project
2. After editing the tests in the __tests__ directory, test them locally

   cd <sitename>
   boostid test

3. Commit and push your changes with git, and get notified on Slack when the coverage tests on CircleCI succeed or fail.

CLI Documentation

You can view the CLI documentation by running:

$ boostid --help
Command suite for Rootid development and testing

Usage: boostid <command> [options]

Commands:
  boostid help [command]                            Output usage information
  boostid setup                                     Setup a Pantheon site for development with
                                                    Boostid
  boostid check-local                               Test if local environment is ready for
                                                    development
  boostid test                                      Run coverage tests locally in a Docker container
  boostid config                                    Read and write global config
  boostid upstream-updates <multidev>               Create multidev as copy of "dev" and apply
                                                    upstream updates
  boostid ter <cmd> [args...]                       Run terminus commands
  boostid ci-update-meta <git_url>                  Update CircleCI (specified by the git url)
                                                    environment variables and SSH keys
  boostid ci-local <job>                            Run CircleCI job locally using Docker
  boostid ci-trigger <git_url>                      Trigger CircleCI workflows for specified the git
                                                    url
  boostid create-github-repo <username> <reponame>  Create a Github repository from the command line

Options:
  --help, -h           Show help                                                           [boolean]
  --site, -s           Manually set pantheon site name                                      [string]
  --machine-token, -m  Machine token for Terminus cli                                       [string]
  --ci-token           CircleCI API user token                                              [string]
  -v, --version        Show version number                                                 [boolean]

Config File

There should be a file boostid.config.js in your project root.

It should export an object with the following properties:

• name: Unique Pantheon site name
• id: Unique Pantheon site id
• multidev: Pantheon multidev id for running upstream-updates tests
• bucket: AWS S3 bucket for hosting visual regression tests (optional)

Running Tests Locally

You can run your tests locally in a number of ways:

• In a Docker container (Recommended)

  boostid test

• On the current machine i.e. without Docker.

  boostid test --no-docker

• On the current machine i.e. without Docker, AND Chromium runs in non-headless mode, so you can watch the tests as they run.

  boostid test --dev

• Using CircleCI CLI (requires the official CircleCI CLI and Docker to be installed)

  boostid ci-local

Testing with Jest and Puppeteer

Any .js files in the __tests__ directory of your project will be run as Jest tests. This means that you must use test mock functions to create your tests. In Jest, those are: beforeAll, beforeEach describe, test, etc.

A few Puppeteer global variables are provided for convenience: browser, context, and a default page (See jest-puppeteer-environment).

Also the global function expect allows you to create assertions in the test. See the expect documentation and expect Puppeteer documentation (which adds some convenience methods like expect(page).toMatch('Some string that should show up on the page')).

Finally, Boostid provides numerous helper functions in the tests directory. Example:

const tests = require('boostid/tests');

test('My test', async () => {
  await tests.submitForm('#form-selector', {
    name: 'value',
  });
});

Helpful Links

Jest Testing

• https://jestjs.io/docs/en/getting-started

Puppeteer API headless Chrome testing

• https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md

Jest Testing with Puppeteer

• https://www.npmjs.com/package/jest-environment-puppeteer
• https://www.npmjs.com/package/jest-image-snapshot
• https://www.npmjs.com/package/expect-puppeteer