Unique element identification for tests

When writing tests and ensuring they will continue to work even when the markup within an Angular component changes, one of the best options is eliminating the dependence on HTML markup via specificity selectors and using unique identifiers. You still need to maintain the checks for actual content and logic, but you will see a significant reduction in maintaining the specificity selectors. They may look as easy as putting the attribute onto the HTML elements. This is reasonable, but there are established good practices to separate concerts of attribute and test or automation specific identifiers. A good solution is to pick one of the common custom attributes widely used in the testing community. The most common examples would be:

These attributes are even prioritized when using Chrome dev tools recorder.

Storing the test IDs

In an ideal world, you should store the IDs somewhere as constants to make sure both your app and tests use the same identifiers.

The easiest approach would be a simple object split into pages and components that could look like this example:

It is a good solution but we can already see some flaws:

• There is no simple mechanism to prevent the same values of the selector.

  • We are not 100% sure everything is unique and mistakes can happen.

• Selectors could get messy and would require some naming convention.

  • This introduces complexity to naming the selectors which again would require some check as we do not want this to be a manual process.

• This object would end up as part of the final JS bundle shipped to production (if test IDs are kept in the prod build).

  • Not ideal as it will grow with test coverage and could weigh significant kBs in the initial page load.

These concerns can be addressed and elegantly solved with TypeScript types.

Making it all type-safe

We use TypeScript so why not take advantage of build checking if we didn’t make a typo in our element selector?

Let’s convert the object from the previous example into a type:

What did we just do here:

• The runtime object was converted to a TS type, and now it does not exist outside of compilation (build) time.

• The selector values were replaced by void.

  • Main reason is that we will never need a value as we will only use the keys of this object type.

• Type ensures that there is always just one unique key per instance.

  • We can leverage this even further and say that this ensures that there is always one unique way to identify each nested key via a path to that particular key.

    • E.g.

With this our selectors are:

• Stored at a single place.

• Shared between the main app and app-e2e test, but also accessible to all other importers like component libs.

Selectors naming & good practices

• Top selector groups should be routed pages and reusable components.

• It is beneficial if the last item in the chain name refers to the element type.

  • For example: , or you can also include more generic suffixes like or to distinguish them in selectors.

• Do not nest too much, nesting in 3-4 levels is a sign for splitting into reusable components or at least for a separate group.

Type-safe map of selectors

We can leverage the Turing completeness of TypeScript and write some helper types that will serve as a very handy mapper from the E2E IDs map to “dot notation” selectors. You don’t need to touch these types, but for the convenience of understanding what is happening there, I’ve included documentation comments. Feel free to copy-paste as is 😅.

Usage itself is fairly straightforward. Just export the union of all possible strings and use your preferred separator (for us it’s just a dot as we like dot notation in selectors).

E2E test id directive

In Angular projects, a simple directive may be written offering better code suggestions and strong typing of IDs.

You may notice it does not do anything. Its only purpose is to tell Angular we are intentionally putting these attributes on elements and specify what type we use for the selector suggestions.

If you want to leverage the native data attribute for Chrome to start picking element selectors automatically, you could also bind that value in a directive easily via decorator.

Selector helper function for E2E tests

In the (Cypress) E2E test we can again leverage the type safety and create a simple helper to access the elements.

Having this helper we can now write simple type-safe checks like this one for a page title.

This could get lengthy so what you could do to improve DX further is create a custom Cypress command for get and chainable find.

The usage in tests would get simplified to just:

Recapitulation

✅ Selectors are stored in one place.

✅ All selectors are unique.

✅ No additional bloat to JS bundles in the form of big selector object constant.

✅ Fully type-safe on both ends (element E2E ids & E2E tests element getters).

✅ Less maintenance as you are just extending one type-map by new selectors.