Background
The Aikau team is committed to providing weekly backwards compatible releases.
It is important to understand that whilst we guarantee that all configuration options for a widget will be honoured in future releases (unless deprecated for removal in the next major release), we will not guarantee that the internal implementation of any given widget will not change. This means that the HTML structure for any given widget could potentially change in any release.
This means that you cannot not rely on HTML structure or CSS classes used within a widget for customizing its appearance (the correct approach is to create a theme file that overrides the necessary LESS variables). It also means that any automated tests cannot rely on CSS selectors continuing to work for all future releases.
Solution
The Records Management (RM) team have recently run into this latter problem with their automated testing and have asked us to resolve the situation. Therefore from version 1.0.57 we have started to externalise the CSS selectors that can be used for automated testing.
These are provided in the form of Java ResourceBundle property files that are published as the test resources for the Aikau project. They are Java properties because the RM team are testing using Java based Selenium. However, it is possible to simply unpack the JAR file into your project for Intern JavaScript based testing.
We won't simply be providing the test selectors - we will also be updating our own unit tests to use these properties files in our own testing. This means that when we make a change to the struture or CSS classes of a widget we will need to update the associated selectors property file in order to ensure that our own unit tests do not break. This means that it will be safe to rely on these test selectors in your own testing (providing that the version of the Aikau tests JAR used in tests matches the version of the Aikau JAR that is being tested).
Process
Because the Aikau code base is so large and the Aikau team is so small, it will not be possible to do this in a single sprint. Therefore we will be providing the test selectors on demand. The RM team have provided us an with an initial set to provide and all new tests will be written using externalised selectors - however, full conversion is expected to take a considerable length of time. Therefore if you have a need for specific selectors in your tests then it is recommended that you raise a feature request on JIRA or an issue on GitHub (or better yet - provide the selectors yourself via a pull request!)
We will provide one properties file for each Aikau module, each property will have a comment to indicate what it will be used for and in most cases the property will be parametrized so that widget identifiers (and when required indices) can be provided.
Examples
This is an example excerpt from the alfresco/forms/controls/MultiSelectInput properties file:
# A specific result in the drop-down
nth.result=#{0}_CONTROL_RESULTS .alfresco-forms-controls-MultiSelect__results__result:nth-child({1})
This shows an example of a selector that allows you to find a specific result in MultiSelectInput form control drop-down menu. In Java testing you would access that property as follows:
ResourceBundle selectors =
ResourceBundle.getBundle('alfresco.forms.controls.MultiSelectInput');
String pattern = selectors.getString('nth-result');
String selector = MessageFormat.format(pattern, 'WIDGET1', '4');
In the Aikau unit test framework we are importing the 'properties-reader' package in order to be able to load the properties as follows:
var selectors = propertiesReader('./src/test/resources/test-selectors/alfresco/forms/controls/MultiSelectInput.properties');
var selector = selectors.get('nth-result').replace('{0}','WIDGET1').replace('{1}','4');
Summary
Aikau has provided backwards compatible releases for developing future proof Alfresco Share customizations and standalone clients and is now going to be provided a future proof way of testing those solutions.
