Onboarding

Nala Automation Structure

In a general sense, the Nala project's goal was to provide a solution that developers could understand quickly with an as little amount of overhead as possible. To this end, dependencies for the project are minimal as well as file configuration and test setup.

When you first install Playwright and check out Nala out-of-the-box configurations are already set up in order to quickly get going with development. For further discussion on configuration options and definitions, you can see Playwright's documentation.

The overall folder structure is as follows with configuration files for Playwright and IDE extensions below:

\nala
  ┣━ \.github\workflows
  ┣━ \envs 
  ┣━ \features
  ┣━ \selectors
  ┣━ \tests
  ┗━ \utils

The following sections will explain each.

Environments

Nala handles environments for different domain path testing by the use of the envs.js file. All site environment domains that need to be tested across different test files should be housed under the /envs/envs.js file. Each environment should have a 'tag' label and then the environment to be tested listed, for example:

'@milo': 'https://main--milo--adobecom.hlx.live',
'@milo_prod': 'https://milo.adobe.com/',

Additional environment domains should be added as needed to this file. Full page paths are NOT to be housed in the envs.js file but instead will be housed in the features directory for the respective block spec file.

As a word of caution, it is best practice to NOT use 'hlx.page' domain URLs for environments running in the production CI since these URLs are not cached and will come with heavy resource usage against the Franklin services. 'hlx.live' URLs are best conceived as staging domains and should be used for all testing outside of production tests. Test development for blocks currently under development can use the 'hlx.page' domain URL temporarily but must be removed before merging a test into the production CI.

Features

The features directory contains different spec.js files for each feature or block (blocks are what authoring teams use to create separate pieces of content on a webpage) that may be used across a site. Feature spec files define the test title (generally the block name), URL paths where the block will be tested, the environment tag(s) that should be used in conjunction with the page paths, and the overall test tags that could be used to filter which tests to run.

For example, I have a Marquee block that has different features to it that need to be tested. Maybe the Marquee I'm testing is a large variant of the marquee that has a button on it. So to set up my feature spec file I would do something like this:

module.exports = {
  name: 'Marquee',
  features: [
    {
      name: '@marquee',
      path: '/test/features/blocks/marquee',
      envs: '@milo @milo_prod',
      tags: '@marquee-large @large-button',
    },
  ],
};

The important parts are under the features array, aptly "name, path, envs, and tags". The name will be used as the title of the different test execution(s), but also can be used to filter which test to execute (you can have multiple lists of features that use the same tag see the README for Nala here).

The "path" should be the relative URL of the webpage you plan on testing the said feature on. Paths can also be an array list of URLs comma-delimited.

The "envs" should be a space-delimited list of all the environment domains you would like the said path(s) to be tested on. This is where the envs/envs.js file label tags for your environments get used to create the full path URLs for your test(s). Make sure your environment label tags are defined and listed in the envs.js file as shown in the previous section.

Lastly, you have the "tags", these should be a space-delimited list of all the different test filters (see here for Playwright test tagging documentation) you would like to provide for test runner execution. For example, maybe I want to test all buttons across my site and not just the ones in a marquee, I could have multiple tests that use the tag '@button'.

Selectors

For a specific feature spec file there should be a coinciding selectors.js file. The selectors file includes a tag label and its string value for the CSS selector, XPath, text, etc desired to find specific elements on the page for the test. Below is an example of a selector file that uses class names to find different elements on a webpage that has a modal.

module.exports = {
  '@dialog': '.dialog-modal',
  '@close-button': '.dialog-close',
  '@curtain': '.modal-curtain',
};

Playwright uses various Locators to find elements on a page. The tag/value pairs in your selectors file will be used for these locators.

Tests

Continue to Setting up your development environment