Living Styleguide and automated visual tests with DSS and Galen

tl;dr: My team was tasked to convert a client’s white label platform from a desktop-first, fixed width layout to a fully responsive one and also to improve frontend code quality throughout the project. A living styleguide and automated visual regression tests helped us to meet our goals.

If you are only interested in our setup, skip to Setup – if not, bear with us while we set the stage.

Context#

We recently took over a project that is at heart a white label component library built on CQ (AEM) and used to power a great number of brand, sub-brand and campaign websites for a big industrial company. The project was originally started by a competitor and then taken over by various agency teams before it finally landed on our desks. As is common in large projects, the code had grown organically and we found many different flavors and best practices (some already outdated) when we started a high-level inventory.

Our first task was to implement a new campaign website for a sub-brand: in practice, we “only” had to create a new responsive theme, working exclusively in the LESS files. We immediately pinpointed two major challenges for us:

1. We didn’t know the HTML markup for the components
2. We didn’t yet understand the LESS architecture (such as it was)

The HTML markup was (and still is) suffering from a couple of drawbacks. It was conceived without the requirements of a responsive website in mind and as such sometimes lacking containers or class hooks that would have made our life easier. On the other side, AEM adds a plethora of containers and classes that we didn’t really need and much less dared to lean on.

The LESS files were a diverse bunch; hardly commented, rarely using mixins, sometimes using variables. The responsiveness that had already been implemented was based on a set of 17 distinct media queries mostly going from xx pixels to yy pixels and following a desktop-down approach.

Goals#

Our code inventory led us to define clear goals that we wanted to work towards during our campaign project:

1. Improve the LESS code quality
   1. Move to a mobile first approach with less media queries
   2. Let smart mixins do the hard work for us, i.e.
      1. Introduce a mixin-based grid system for layout tasks
      2. Introduce a mixin-based typography pattern system
      3. Set up variables in a way that many future theme adjustments could be managed by tweaking variables, not CSS declarations
2. Facilitate maintenance
   1. Comment liberally
   2. Make the code more readable by agreeing on and following a code style
   3. Create a living styleguide so components can be viewed in isolation and without CQ or existing demo content
   4. Set up a system for automated visual tests as a first line of defense against regression bugs

Setup#

Living Styleguide#

We agreed that a living styleguide would be just the thing to help us with both our challenges and our goals:

• We would get to work closely with the HTML and be able to see and play around with it in an isolated environment without need for client content
• We would be able to refactor the LESS components one by one and track our progress by looking at the list of components in the styleguide

After reviewing a few of the many, many solutions, we settled for DSS (Documented Stylesheets). Most styleguide tools parse certain comment syntax in the referenced stylesheet files to create the styleguide HTML, and DSS is no exception. What made us choose DSS over the alternatives is the fact that the parser makes the data available as JSON and lets you do with it whatever you want. We use Handlebars to loop through our JSON and output an index.html with a list of our components as well as a componentName.html for each component.

We also extended the generic parser (includes component name, description, example markup and a rendered example of the component) with custom parsers:

• A “mobile first” tag is added to the component if the responsive approach was converted
• A list of configurable visual parameters can be added as a quick reference for designers that need to adapt the theme
• Mixins can be documented with a list of components that use them so it is easy to keep track of possible side effects

The living styleguide is part of our project’s Grunt task workflow and can be automatically updated after every change to any LESS file (this makes sense when we’re working against the styleguide but can be omitted if we chose to work against a local CQ server and want to save grunt execution time).

Automated visual tests#

Once we had the styleguide up and running with the first components, we looked for a way to set up visual tests and quickly settled for the Galen framework. Galen is developed and used by eBay, so we hoped that it would be actively maintained for quite a while yet. The premise of Galen is simple: you define a number of test specs and test cases using a kind of pseudo-english syntax and then run them. Feedback is given on the command line and as a generated HTML report including screenshots.

We run Galen as part of our Grunt task workflows and have tasks for running the complete test suite as well as only a single component test case. Similar to automatic updates to the styleguide, it can make sense to have Galen react to any change or to only run the test suite a few times a day.

Results & Lessons Learned#

Our decision to invest in a living styleguide and visual tests although they had to be retrofitted to an existing project has paid off tremendously:

• It was quite liberating to simply work on components after having had trouble getting demo content
• It was also easy to keep track of our progress in various stages of the refactoring process and watching the styleguide grow gave us great visual feedback and a warm, fuzzy feeling of achievement
• Running Galen and visual tests gave us great confidence and kept us sane when we were tweaking things in central mixins

However, we also encountered a couple of new challenges that we will need to work around or fix in the future:

• The additional effort needed to document the LESS code and write test specs was not included in the original project estimation and schedule because both preceded our decisions
• Especially the creation of test cases suffered from our lack of time (sounds familiar?)
• Many components are heavily nested and have contextual styling quirks (i.e. download in textimage in accordion in article); this is very hard to document via comments in LESS files without creating a lot of bloat

Vision#

We want to develop and maintain a micro-framework of helpful tools for frontend development in CQ (AEM) projects. The framework will be based on node.js and Grunt and be available to coworkers as a (company internal) repo. We are looking to open source our work as soon as possible, if time and project constraints permit it — but your feedback is appreciated right now! Have you tried similar approaches? Does our solution make sense? Please share your thoughts!