Simple Test Demo

Create a simple test

These instructions assume you have already checked out the Nala repository and have created a branch off of "main". You may feel free to create your own Milo-based test page within your site's own Sharepoint with a Milo block added to the page and then follow along with creating your own test. If you are just wanting to get the knack for Nala test writing, feel free to copy the examples below into the three needed test files. Or if you would like to follow along with a demo video for creating a test check it out here.

1st step add your environment

Open up your IDE of choice, though Playwright and Nala are best implemented with VSCode. Then open the /envs/envs.js file and add your site's environment to the module exports if it hasn't already been added. Make sure you label the environment with a unique name. I've added my example of milo's hlx.live URL below as an example, which is already included in the envs.js file.

module.exports = {
  '@milo': 'https://main--milo--adobecom.hlx.live',
};

2nd step add your feature spec

Find the /features directory and add your (featureName).spec.js file. Create a module.exports object that includes an overall name for the module with a features object that includes the name of the feature, the URL path(s) that you will test the feature on, the environment domain(s) you will test the URL paths from (remember these come from the environment you just added to the envs/envs.js file), and the test filters/tags you would like to use to denote what portion of the feature you are testing. I've added an example feature spec, which you can use for a demo block test. Name the file demo.spec.js in the features directory.

module.exports = {
  name: 'Demo Block',
  features: [
    {
      name: '@demo',
      path: '/test/features/block/demo',
      envs: '@milo',
      tags: '@demo-button',
    },
  ],
};

3rd step add your selectors

Find the /selectors directory and add your (featureName).selectors.js file. It's best practice to name the selectors.js file using the same name you used for the spec.js file above to maintain the association of the two files. Within your selectors file create a module.exports object that contains a comma-delimited list of element selectors used to locate and test your feature on the webpage. The list will be a key/value pair of the elements using tag names for the keys and then the type of locator string/text used for finding the element. The available values for locators can be CSS Selector strings, class names, ids, text, HTML tags, XPaths, element attributes, etc. See here for reference. Please note, using XPaths take more time for the Playwright Test Runner to locate elements, if there are other options for finding an element it is best practice to do so. I've included an example demo.selectors.js file module.exports object below that you can use.

module.exports = {
  '@marquee-large': '.marquee.large',
  '@demo-button': '.marquee .con-button',
  '@large-button': '.marquee.large .con-button.button-XL',
};

4th step add your test

Find the /tests directory and add your (featureName).test.js file. As before, it is best practice to name the test.js file using the same name used for the spec.js file above to maintain the association of the spec, selector files with its test. The demo test will check that a button is present on the marquee block. It is a very simple assertion check but it shows the usage of finding an element using the selectors file tags, navigating to a page using Playwright's page class, and then validation for test pass/fail status.

All tests will need to bring in the 'expect' and 'test' classes from Playwright, you will then import your feature spec file, the parse.js script (this will break up all your values, paths, and environments in your spec file into an object that can be iterated upon within your test), and your selectors file. Then parse your spec file returning the name and features. Lastly, add your test logic. Different test cases can be grouped together within a logical name for test organization. You can create a test() for each test case or include multiple test cases within a test(). It is entirely up to you and there is no right or wrong option or best practice. However, it is best practice to add a test.describe() to give your test method(s) a logical grouping.

The test.describe() takes a name for a parameter, which you can use the "name" variable returned from parse.js. Then you iterate against all of the environment, paths, and test tags parsed within the features object returned from parse.js. Each test() method takes a test title and an asynchronous method as parameters. Playwright is unique in that all test methods and calls are executed asynchronously. This is why various calls require the keyword "await" to be added before the call to wait for the call's execution to return before another surrounding code is executed.

In my example below, we will pull in our created demo.spec.js, demo.selectors.js files created before. The test will iterate over our milo domain and page path(s), in this case, there is only one, and test the demo block button. The test will first go to the page using the URL that was created from the parser, search for the "first" demo button using the selector for @demo-button and then validate it should be there.

import { expect, test } from '@playwright/test';
import demo from '../features/demo.spec.js';
import parse from '../features/parse.js';
import selectors from '../selectors/demo.selectors.js';

const { name, features } = parse(demo);

test.describe(name, () => {
  features.forEach((props) => {
    test(props.title, async ({ page }) => {
      await page.goto(props.url);
      const el = page.locator(selectors['@demo-button']).first();
      await expect(el).toBeVisible();
    });
  });
});

Run your test

From VSCode

From Command-line

Continue to GitHub CI/CD Setup