Cypress Tools for ApostropheCMS

Automated functional browser tests are an important part of quality assurance for enterprise websites and web applications. Cypress is an industry-standard, open-source library for carrying out automated functional browser tests. This module provides a collection of conveniences for testing ApostropheCMS sites and applications within Cypress.

Those conveniences include utilities to manage a test "starter" database (fixtures), create users, log in, log out, open various admin dialog boxes, and so on.

Read on to learn how to get started with the Cypress Tools.

Setup

1. If you are new to Cypress you should visit the Getting Started section of the documentation and install and initialize Cypress for your Apostrophe application according to their instructions.

2. In order to be able to reset your application state before each test, you need to install the MongoDB Tools for your operating system. You may have those installed already especially if you already have a local MongoDB server installation.

3. Pre-populate a local instance of your site with an initial database that suits your tests. If you plan to use the addUser command in your scenarios, be sure that username does not already exist in the database you plan to provide.

If you need to reset your local database to be empty, you can use:

node app @apostrophecms/db:reset

⚠️ don't do this in production!

Then, prepare a dump of your application database in your project's cypress/apos-db folder:

mkdir -p cypress/apos-db
mongodump -d=yourDbName --archive=cypress/apos-db/default --gzip

yourDbName should be changed to match the value of shortName in your application app.js when you are running tests. The --gzip flag is mandatory.

We recommend committing this small mongodump file in git with your project.

4. Install Cypress Tools for Apostrophe

npm install @apostrophecms-pro/cypress-tools --save-dev

5. Integrate Cypress Tools for Apostrophe

Add the minimal required configuration to your cypress.json

{
  "baseUrl": "http://localhost:3000",
  "env": {
    "@apostrophecms-pro/cypress-tools": {
      "apiKey": "cypressAPIKey",
      "mongoURI": true,
      "dbName": "yourDbName"
    }
  }
}

Make sure that you make the following changes to the above:

• Set apiKey to your existing Apostrophe API Key with administration role or add new admin API key for your Apostrophe installation
• Set mongoURI to a different value if you don't want to use a MongoDB instance on your own computer, without credentials
• Change dbName to your project's database name (usually the same as shortName in app.js)

Next, open cypress/plugins/index.js and modify it like this:

// cypress/plugins/index.js
const { plugin } = require('@apostrophecms-pro/cypress-tools');

/**
 * @type {Cypress.PluginConfig}
 */
module.exports = (on, config) => {
  plugin(on, config);
  return config;
};

Open cypress/support/e2e.js and add:

require('@apostrophecms-pro/cypress-tools/commands');

5. Add your first application test in cypress/e2e/it-works.cy.js:

// cypress/e2e/it-works.cy.js
describe('Apostrophe', () => {

  beforeEach(() => {
    cy.task('apos:dbReset');
    cy.addUser('admin').as('user');
  });

  it('it works', function () {
    // Login with role `admin`
    cy.login('admin');

    // Select and expand the user menu
    cy.getAdminBar()
      .contains('button', this.user.title)
      .click();

    // Find the Log Out expanded button 
    cy.contains('button', 'Log Out');
  });
});

Note: you might want to delete the auto-generated specs in cypress/integration first.

Running the tests

First, make sure your app is running so Cypress can talk to it. Leave npm run dev (if you have a dev task in package.json) or node app running in a separate terminal window.

Then type npx cypress open in your CLI OR add "cy:open": "cypress open" to your package.json scripts and run npm run cy:open in your CLI. Find the it-works test and click it. You can also directly run npx cypress run to run your tests in headless mode or create script "cy:run": "cypress run" in your package.json.

Configuration

Be sure to add at least baseUrl to your application cypress.json config.

The settings related to Cypress Tools for Apostrophe configuration should be found in the env.@apostrophecms-pro/cypress-tools namespace of your cypress.json config:

{
  "baseUrl": "http://localhost:3000",
  "env": {
    "@apostrophecms-pro/cypress-tools": {
      "apiKey": "myCypressAPIKey",
      // Use "true" to use the local mongodb database
      // (you can point to an external mongodb provider here if needed)
      "mongoURI": true,
      // Replace with your site's database name / shortName
      "dbName": "yourDbName"
    }
  }
}

Every configuration key can be set via Environment variable just by prefixing the given key with APOS_CYPRESS_. For example in the above configuration apiKey may be set (overridden) by environment variables APOS_CYPRESS_apiKey OR APOS_CYPRESS_API_KEY.

What's next

TODO - API reference, Contributor guide