Download the PHP package aklump/dom-testing-selectors without Composer

DOM Testing Selectors

This library offers a PHP solution designed to add specific markup to your DOM for testing purposes. By default, it configures a data-test attribute for DOM elements, as shown in the examples. The library is intended to be integrated into a server-side rendering pipeline, which generates your markup.

This attribute should be used exclusively for targeting elements in your tests. Separating concerns in this way helps prevent test fragility that can arise from relying on classes or other multipurpose attributes that you may not control and could change unexpectedly. By using a dedicated data attribute for testing—one that you control—you can ensure that your tests remain stable and reliable over time.

Install with Composer

1. Require this package:

Selectors

You may also add a group to the selectors, which will prefix the attribute value:

Naming Convention

Be aware that in an effort to reduce confusion and errors, the provided \AKlump\DomTestingSelectors\Selector\AbstractSelector has an opinion about naming convention.

To change this behavior you should create a custom selector class, overriding \AKlump\DomTestingSelectors\Selector\AbstractSelector::applyNamingConventions.

Using a Custom Attribute

This example will illustrate how to change the attribute to data-cy, which you may want to use while testing with Cypress. Simple create a custom selector class and use in place of DataTestSelector.

To learn more about selectors, refer to \AKlump\DomTestingSelectors\Selectors\AbstractSelector.

Using Classes as Testing Selectors

The included \AKlump\DomTestingSelectors\Selector\ClassSelector can be used instead of \AKlump\DomTestingSelectors\Selector\DataTestSelector if you want to use CSS classes (e.g. t-foo) for selecting your elements. Notice the naming convention is altered for classes, using hyphens instead of underscores.

Handlers

Handlers do the work of adding the selector markup to your HTML. The \AKlump\DomTestingSelectors\Handlers\StringHandler is provided by this library, to add the selector to HTML strings.

Framework-specific and custom handlers are very easy to add by implementing \AKlump\DomTestingSelectors\Handler\HandlerInterface.

Factories

In practice you may have multiple handlers to cover the full range of elements you wish to markup. This is the reason for \AKlump\DomTestingSelectors\AbstractHandlerFactory. The following example shows how you would write and use a custom factory.

Make it a Safe Factory

Notice that you have to catch if a handler cannot be found for a given element. To get around this you may want to create a "safe factory", that is one which adds as it's final handler the \AKlump\DomTestingSelectors\Handler\PassThroughHandler or something similar (maybe with your own logging). Instead of an exception, the $element will simply pass through unchanged.