Implementing Custom UI Testing for Greater Stability in AEM

How confident are you that your AEM website is working as it should? Many developers and some tech-savvy marketers might assume that a small code change won’t break the website. Unfortunately, this isn’t always the case.

What’s worse is when an error is first noticed by the CEO — or even worse, the customer — but is missed by the marketing or development team. Luckily, enterprises can introduce automated user interface (UI) testing to continuously test all of the features on their website overnight and be sure that everything is working as it should. If they aren’t, those errors can be fixed before they impact the user experience or revenue.

The earlier you can implement an automated testing strategy, the better. AEM offers a “Custom UI Testing” feature in Cloud Manager to help. In this post, we’ll explain how to use Custom UI Testing in Cloud Manager to improve stability when releasing new changes to your application.

Cloud Manager CI/CD Pipelines

Cloud Manager is an Adobe Product that enables organizations to self-manage Adobe Experience Manager hosted in the cloud. If you have an AEM instance hosted in the cloud (on Adobe infrastructure), either AEMaaCS or AEM with Adobe Managed Service(AMS), Cloud Manager is your entry point for managing it.

One of the most commonly used Cloud Manager features for developers is the CI/CD Pipelines. There are several types of pipelines, each serving different purposes, and the official documentation provides all the details.

For this post, it’s important to note that the pipelines consist of a series of steps that enable you to deploy your custom code into your AEM instances.

While discussing testing, it’s important to note that Cloud Manager Pipelines include specific steps to ensure the deployed code is stable and meets our requirements. In a nutshell, these steps are:

• Product Functional Testing: Adobe owns these tests, ensuring that the custom code introduced into AEM will not break the product.

• Custom Functional Testing: Customers can add these Java tests to evaluate how their application interacts with the AEM cloud stack, including components like the CDN and dispatcher. These tests primarily focus on the application's back-end functionality.

• Custom UI Testing: These tests focus on the application's user interface. The following sections will discuss this in more detail.

It’s also worth noting that not all of the steps mentioned above are mandatory; however, some may be required for specific types of pipelines. You can refer to this helpful chart from Adobe to know which ones.

The “Custom UI Tests” Step

This step in the Cloud Manager Pipelines serves a similar purpose to an End-to-End (E2E) test. It aims to evaluate your application or website's various flows by simulating real user scenarios. This process ensures all integrated components—front and backend—function together as intended.

However, this doesn’t mean you should discard your existing automated tests or use this step as a substitute for all your automated testing. This step is explicitly intended for critical workflows tied to your website.

For instance, the ability to book a room on a hotel booking site could be a prime candidate for inclusion in the custom UI tests. Remember that Adobe recommends keeping the “Custom UI Tests” step execution times under 15 minutes, as longer tests can negatively impact pipeline efficiency. If you find that some tests exceed this duration, consider moving them out of the pipeline and incorporating them into a separate testing strategy.

UI Testing in the AEM Project

The AEM Project Archetype includes the ui.tests module, designed to store all tests executed during the 'Custom UI Tests' step in the Cloud Manager Pipeline.

These tests can be developed using various testing frameworks, such as Selenium, JavaScript, Java, and Cypress, and are packaged in a Docker image for straightforward execution. However, Adobe encourages using Cypress for its many benefits, including real-time reloading, automatic waiting, and a simple, intuitive syntax. This recommendation has been the standard since Archetype v43.

Demo

Let’s create a straightforward Cypress test that will run as part of the Custom UI Tests step when the Cloud Manager Pipeline is executed.

Set Up the Necessary Config Files

We will use Cypress for this demo. As mentioned earlier, Archetype version 43 and above has all the necessary configurations to use Cypress as the testing framework. However, if your project was created with an older version, the default configurations will be set to Selenium. Switching to Cypress is simple: copy and paste the files from the ui.tests folder of the latest Archetype.

Write a Test Case

Imagine we have a demo site where the 'Blogs' are critical to the business. For this reason, we need to write a simple UI test to validate whether this section is populated and accessible.

In the code below, you will find two tests. The first test checks if the navigation bar displays a "Blog" link that successfully redirects to the Blog page when clicked. Upon reaching the Blog page, the second test ensures that a "Related Blogs" section is visible and contains more than one link to related blog posts.

describe("Blog Page", () => {

    it("should display a Blog link in the navigation bar that redirects to the Blog page", () => {
        cy.visit(Cypress.env("AEM_PUBLISH_URL"));
        cy.get(".cmp-navigation__item-link").contains("Blog").should("be.visible");
        cy.get(".cmp-navigation__item-link").contains("Blog").click();
        cy.url().should("include", "/blogs")
    });

    it("should display a Related Blogs section on the Blog page", () => {
        cy.visit(Cypress.env("AEM_PUBLISH_URL"));
        cy.get(".cmp-navigation__item-link").contains("Blog").click();
        cy.get("h2").contains("Related Blogs").should("be.visible");
        cy.get('a[href*="/blog"]').then(($links) => {
            expect($links).to.have.length.greaterThan(1);
        });
    });
});

Verifying the Cypress Test

You can run your tests locally against a local or remote AEM instance by configuring the environment variables mentioned in the README.cmd file from your ui.tests module.

export AEM_AUTHOR_URL=https://author-p***-e***.adobeaemcloud.com
export AEM_AUTHOR_USERNAME=admin
export AEM_AUTHOR_PASSWORD=***
export AEM_PUBLISH_URL=https://publish-p***-e***.adobeaemcloud.com
export AEM_PUBLISH_USERNAME=admin
export AEM_PUBLISH_PASSWORD=***

The test will run silently, allowing you to view the results logs. If you need to debug your tests, you can run Cypress with the browser visible to see the interactions in real time. Use one of the following commands:

npm test  # To run tests silently
npx cypress run --headed --no-exit --browser chrome  # For debugging

One great feature of Cypress is its ability to record videos and capture images during test execution, making investigating any test failures easier. This capability is enabled by default in the Archetype setup, allowing you to review the videos, logs, and images captured during your test runs.

Enabling Tests in Cloud Manager

The UI tests must be explicitly enabled so that Cloud Manager can recognize and execute them during the pipeline execution. To achieve this, you must create a testing.properties file directly within the ui.tests folder and ensure it is included in the Dockerization process. You can refer to the image below for how to do it:

Validating Results

• After running the Cloud Manager pipeline, we can see that the “Custom UI Testing” step, along with the pipeline, ran successfully.

  

• Next, we modified my navigation bar to remove the Blog section, which ensured that the test would fail. As expected, the execution of the Cloud Manager Pipeline failed when it was run.

  

Logs are also available that provide details of the Cypress test execution, including the reasons for any test failures.

Wrapping Up

Whether you already have an automated testing strategy to verify your application's critical workflows, the 'Custom UI Testing' step available in Cloud Manager can help you catch potential business-critical issues earlier.

If you need help with Cloud Manager or any other AEM or Adobe product, Oshyn is available to help. As a certified Adobe partner, we are experienced in the Adobe DXP product suite. We can offer years of content management implementation experience, encompassing the entire lifecycle from design planning to development to post-launch enhancements and maintenance.

Contact us if you want to test and improve your website's reliability.