REI Co-op Engineering

Server Driven UI: Prepared for the Unknown

2024-12-31T00:00:00+00:00

You won’t know ‘till you get there

This blog post is the second half of a 2-part series on a new tool that REI’s Store Technology team has been working on for the last few months - the “Price Change Tool”. You can find Part 1 here.

For folks who haven’t read Part 1, this post comes from the Ascent team, a small-but-mighty product team that builds the iOS app used by REI store employees. Ascent includes features like product search, inventory lookup, and restocking task management. The recent addition of the Price Change Tool gives store employees a digital tool to help re-label items that change price.

At a high level, the Price Change Tool provides two main value-adds over the previous pen-and-paper solution:

An interface that makes properly executing a price change task simple and intuitive.
The ability to filter and sort price change tasks to match your unique work environment.

Thanks to a lot of prototyping work from our designer, Alyssa, we had a clear answer for #1 early into development, but a solution for #2 proved to be more illusive. This is because at REI, we have over 150 stores, each with a unique combination of square footage, staffing, warehouse to sales-floor ratio, traffic, age of the store, etc. This wide variety of cases made it daunting to design a solution that was supposed to work for all users across the enterprise. Even though we surveyed dozens of employees, we still weren’t confident that our initial release would cover all employee’s needs. We knew this was something we would need several iterations to get right, and we needed a way to do that quickly enough to not leave some employees without the support they needed.

How do you plan for the unknown?

Luckily, this tool was truly a greenfield project for us, so we were able to plan ahead for this kind of uncertainty and afford ourselves options ahead of time. The main way we did this was with our choice to leverage server-driven UI (SDUI). In short, SDUI is all about giving the backend as much of the control over how the UI looks as possible, so you can redesign the way the app looks without having to push an iOS app update (because who actually updates their mobile apps on a regular basis!?) While I wouldn’t say we fully embraced SDUI (like Airbnb has), we did choose to make UI components server-configurable wherever we were sufficiently unsure of our solution. As I mentioned before, filtering and sorting was really the place where we didn’t have the confidence to bake a single solution into our iOS app release.

Implementing SDUI in the Price Change Tool

In many ways, the API we created for the price change tool is just a really simple search interface. While it may not have a text search bar, we had to build a way for users to create custom queries that would search over the space of all price change activities.

Luckily, here at REI, we have two entire teams dedicated to search, so we asked for their wisdom on how to get started on such an endeavor.

Their advice: “you don’t want to set up an entire Solr instance for what you’re building.”

While there is a lot of features that come out-of-box with Solr (or Elasticsearch), they warned us that the amount of time and effort it takes to maintain that infrastructure wouldn’t be worth it for us. So now armed with what not to do, we set off to find a way to query our modestly sized database (~1M records) in a maintainable and performant manner.

Querydsl

Since our backend for the Price Change Tool is written in Java, and we connect to a PostgreSQL database through JPA, Querydsl stood out as a good option. Querydsl is an open source library that allows you to construct SQL queries in a simple Java object syntax. We had our concerns about performance when dynamically generating custom queries using Querydsl, but since launch, we’ve seen consistent <10ms P95 response times for our most common queries.

Overall, we’ve been very happy with the decision to use Querydsl. Most of the effort of setting up Querydsl for this use case came from designing a simple query language that we could translate filtering/sorting selections into Querydsl. Below are some high level notes on how the integration works, as well as a bonus section about making Querydsl query typing stronger (an area we found error-prone during development).

Example Implementation: Query Parameters -> SQL

Here’s a simple example of how we can take an arbitrary set of query params and convert them to SQL.

Sample URL

/rs/price-changes/list?filter=brand:Patagonia;department:Basics,Mens%20Outerwear

Converting Filter Values to a JPA query

Map<FacetKey, Collection<String>> filters = Map.of(BRAND, Set.of("Patagonia"), DEPARTMENT, Set.of("Basics", "Mens Outerwear"));

BooleanBuilder querydslPredicate = new BooleanBuilder();

for (Map.Entry<FacetKey, Collection<String>> entry : filters.entrySet()) {
    switch (entry.getKey()) {
        case BRAND -> querydslPredicate.and(QPriceChangeActivity.priceChangeActivity.brand.in(filters.get(entry.getKey())));
        case DEPARTMENT -> querydslPredicate.and(QPriceChangeActivity.priceChangeActivity.department.in(filters.get(entry.getKey())));
    }
}

return priceChangeActivityRepository.findAll(querydslPredicate);

The Resulting SQL Query

SELECT * FROM price_change_activity
WHERE brand IN ('Patagonia') AND department IN ('Basics', 'Mens Outerwear')

Of course, this example doesn’t show what it takes to parse the query string into the appropriate data structure, but that wiring is fairly trivial and only needs to be implemented once. Adding new filters simply becomes a matter of adding a new FacetKey case to the switch statement, and then exposing it as an option to the user.

Exposing Query Options with SDUI

Once we had the ability to convert query params to SQL, we just needed to tell the frontend client how to construct the query string. This is where the power of the server-driven UI pattern comes into play. We designed a flexible JSON schema that could allow us to create the filtering/sorting screens entirely from backend JSON responses. Using that same queryString from above as an example, here is the corresponding part of the API response which the client uses to generate the view:

{
    "filters": [
        {
            "name": "Brand",
            "selected": true,
            "resetQueryString": "?filter=department:Basics,Mens%20Outerwear",
            "options": [
                {
                    "label": "Patagonia",
                    "selected": true,
                    "queryString": "?filter=department:Basics,Mens%20Outerwear"
                },
                {
                    "label": "The North Face",
                    "selected": false,
                    "queryString": "?filter=brand:The%20North%20Face;department:Basics,Mens%20Outerwear"
                }
            ]
        }
    ]
}

While this example is much simpler than what we use in the Price Change Tool, it still shows how the backend can suggest a query that will give predictable results to the frontend, so it can display it in a nice way for the user to select. In addition to label and selected, we have grown this schema to include all kinds of things like doNotReorder, count, hasDefaultSelection, and showInQuickFilterRow. Each of these variables drive a different UI treatment that is hardcoded into the iOS client.

By following this pattern, we can make the iOS client forward-compatible with data the backend may not be ready to supply. We actually did this for our second phase of our pilot release, where I sent our frontend developer several handwritten JSON responses that mimicked what the backend response would someday look like. This way, we were able to support a wide variety of UI layouts without the need for disruptive frontend code changes.

So did it work?

Impact to our users

Since the time we released the tool in our first round of pilot stores, we have been able to rapidly iterate on filtering and sorting options in response to user feedback. We have made over 20 changes to filtering/sorting, each one going live without requiring an app update. In several cases, we have even been able to get a new filter into the hands of all users within a couple of days of receiving user feedback.

Here are several iterations of the app in the last month as we have added more and more filter functionality to the app.

Furthermore, our team has started to see requests to improve filtering and sorting in other areas of the app that don’t leverage this pattern. One of the greatest impacts I believe our team can have is giving our users hope that their technology frustrations can be solved, and they can be a part of that process! (This is the theme of Part 1 of this series)

Impact to our team

From our team’s perspective, this has significantly reduced the time required to deliver features. Here’s a comparison of the process for making a change to filtering in an older part of our app:

Process	Steps	People Involved	Time Involved
Previous Process	1. Make the backend change 2. Make the frontend change 3. Run the entire app through QA 4. Deploy the app to stores (likely with a pilot release before enterprise-wide rollout) 5. (If something went wrong) Push the old iOS app version out to all devices in the fleet	~10 people	Min: A few days Max: A normal monthly release cycle
New (SDUI) Process	1. Make the backend change 2. Use our mature CI/CD pipeline to ensure a suite of tests pass before being released to prod 3. (If something went wrong) A “bad” change can be rolled back in under 10 minutes	1 person	Min: 1 hour Max: A few days

Overall, this design pattern frees our frontend dev and QA resources up to work on major UI changes and features, not plumbing minor data changes into an existing interface.

Bonus Section: Explicitly Typed Queries in Querydsl

Querydsl is great at producing queries that give you strongly typed parameters and responses, but unfortunately the queries themselves are not tied to a specific queryable type. In the Price Change Tool, we frequently need to map a queryString into queries for two different tables. Specifically, these queries may be for a table containing PriceChangeActivity entities, or StyleColorGroup entities. Since the queries aren’t explicitly typed, it’s easy to accidentally do things like this:

BooleanExpression be1 = QPriceChangeActivity.priceChangeActivity.storeId.eq("11"); 
BooleanExpression be2 = QStyleColorGroup.styleColorGroup.style.eq("123456");
BooleanExpression be3 = be1.and(be2); // compiler allows this
priceChangeActivityRepo.count(be3); // runtime error "Cannot find column 'style' in table 'price_change_activity'"

To make it harder to get caught up in this pitfall, I wrote a wrapper class called QueryDslExpression that attaches a JPA entity type to the query. Here’s how that looks in practice:

QueryDslExpression<PriceChangeActivity> qde1 = QueryDslExpression.of(QPriceChangeActivity.priceChangeActivity.storeId.eq("11"));
QueryDslExpression<StyleColorGroup> qde2 = QueryDslExpression.of(QStyleColorGroup.styleColorGroup.style.eq("123456"));
QueryDslExpression<PriceChangeActivity> qde3 = be1.and(be2); // compiler error

This class is trivial enough to show in its entirety here:

QueryDslExpression

public class QueryDslExpression<T extends QueryDslQueryableEntity> {

    private final BooleanBuilder expression;

    private QueryDslExpression(BooleanBuilder expression) {
        this.expression = expression;
    }

    public static <T extends QueryDslQueryableEntity> QueryDslExpression<T> empty() {
        return new QueryDslExpression<>(new BooleanBuilder());
    }

    public static <T extends QueryDslQueryableEntity> QueryDslExpression<T> of(BooleanExpression expression) {
        return new QueryDslExpression<>(new BooleanBuilder(expression));
    }

    public QueryDslExpression<T> and(QueryDslExpression<T> right) {
        if (right == null || right.getExpression() == null) {
            return this;
        }
        BooleanBuilder newBuilder = new BooleanBuilder(this.expression);
        newBuilder.and(right.getExpression());
        return new QueryDslExpression<>(newBuilder);
    }

    public QueryDslExpression<T> or(QueryDslExpression<T> right) {
        if (right == null || right.getExpression() == null) {
            return this;
        }
        BooleanBuilder newBuilder = new BooleanBuilder(this.expression);
        newBuilder.or(right.getExpression());
        return new QueryDslExpression<>(newBuilder);
    }

    public Predicate asPredicate() {
        return this.expression.getValue();
    }
}

QueryDslQueryableEntity

public interface QueryDslQueryableEntity {} // JPA @Entity that you want to query must implement this interface

Store Technology: Building Alongside your Users

2024-09-27T00:00:00+00:00

The joy of developing solutions for, and with, real people

On the path to “Product-Led”

When working on a product development team, perhaps the most important question to answer is “will this meet the customer’s needs?” Depending on the product you’re building and who your customer is, it may be very difficult to answer this question. This question may be paired with other questions like “what are the customer’s needs?” or “who even are our customers?” While there are many opinions on how to most effectively answer these questions, REI technology made the decision a few years ago to embark on the journey towards a particular philosophy: “product-led”.

The fundamental premise of product-led growth is that the product you develop should be the primary driver of your business. Now I hear what you’re saying, “REI is not a software company, your product isn’t an application”, and that is true! But we believe that a number of the core tenets of product-led growth can help us build better technology solutions, to real user problems, faster.

If you want to learn more about the ideas behind product-led, empowered product teams, and a vision for extreme customer-centric solutions, I highly recommend reading this article by Marty Cagan. The goal of this blog post is not to sell you on product-led ideas, but I will frequently refer to ideas from Marty Cagan’s book Inspired, and I believe he has some great ideas on how to answer these above questions effectively.

Why is it so hard to know what the user wants?

Problem #1: The user is in a galaxy far, far away

If you are on a product team reading this, you already have a list in your head a mile long about why it’s difficult to hear real feedback from your users. Maybe your list includes things like:

Focus groups are expensive
The only feedback we get in our in-app feedback channel is vague, and we can’t follow up to ask more questions

You could have the most agile team in the world and still struggle with how to clear these hurdles. For most technology products, these are real constraints that mean developing quality solutions requires a good mix of intuition, research, and a lot of resources. And that’s just the way it is… or is it?

Problem #2: Competition

In the vast majority of software solutions, your user has the choice to go with the competition. This inconvenient fact means you can spend lots of time building something that you think will meet your user’s needs and, in the end, you will learn that it wasn’t enough to drive conversion. The product-led growth mindset aims to solve this by building the best-darned-product your user has ever seen… but sometimes you just get it wrong. Sometimes your journey of learning what a user wants gets cut short by them walking away.

What if we didn’t have to worry about either of those issues?

Imagine a world where product teams could build solutions without competition, could talk to their users whenever they wanted, and could build persistent relationships with individual users. That would almost be too easy, right?

Enter the field of employee tools.

Anyone who has ever worked a job that required the use of employee-facing software just rolled their eyes at that last statement. We all have stories of a legacy tool that is mission-critical to our business and has been left on life-support for over a decade. Or maybe you have a story of a normal, every day task, that requires you to endlessly jump back and forth from one system to another. Chances are, this tool you’re imagining right now, is something you long ago stopped hoping would get better. You don’t file IT tickets for it anymore because you know “this is just the way it is”, or you “have a work-around”. If asked, you probably would assume there’s no one at HQ that even thinks about this software.

It seems at least a little ironic that the one place where product teams have nearly unlimited access, to a user base that has no access to competing solutions, is the same place where solutions so often get neglected. But now is where I am going to intentionally avoid diving into “why” this phenomenon is so common. To be honest, I don’t have a good answer as to why so many organizations let employee tools fade into unsupported legacy software, but what I do have to offer is a vignette of how cool Store Technology can be, if handed over to an empowered product team.

Ascent: built with employees, for employees

Fall in love with the problem, not the solution. - Uri Levine

The Problem

Ascent is REI’s in-house employee-facing iOS native app that is used by the “green-vests” to power sales floor operations. When you walk up and ask “Do you have this tent in-stock?”, the tool they use to answer your question is likely Ascent. Beyond inventory and product information capabilities, we have added a number of bespoke tools to Ascent that retail employees use to aid in their day-to-day operations. For the purposes of this article, we will focus on the “Price Change Tool”, a tool we have recently developed.

The Price Change Tool does exactly what it sounds like; it helps employees re-sticker products when their prices change. Previously, price-change days involved printed pieces of paper with a list of SKUs and (stale) inventory data (it’s hard to do a cache-clear on a paper list!). Employees would walk around the store, typing SKUs by-hand into Ascent, relying on handwritten notes, symbols, or highlighters to keep track of progress.

Even if this wasn’t explicitly unspoken among our team, I think it was pretty universally thought “how hard could it be to put a list of SKUs into an app?” Spoiler: it can be really hard! The amount of complexity that you can introduce with a pen and paper can be quite difficult to reproduce in an easy-to-use digital tool.

Research Pt. 1: The Listening Tour

One of the very first steps our product team takes when tackling a problem is to go talk to our real users, in stores. This can look different from one problem to the next, but the last few major endeavors we have embarked on has started with what we call “a listening tour.” This consists of members of our team (ideally, representatives from at least Product, Design, and Engineering) traveling to a handful of stores across a region and asking them about their current process.

When planning a listening tour, we intentionally try to choose a collection of stores we’ve never been to before, because part of the value of this trip is building new relationships with store employees. As I alluded to above, it is common for employees to think “no one at HQ is working to make technology better… so why would I provide feedback” It is so cool to have conversations with store employees and see their eyes light up when you say you’re working on a solution to a problem they’ve faced for years. Not just is there excitement that this problem may get fixed, but you see a glimmer of hope that maybe other problems they have can be addressed as well. For every listening tour we’ve done, we have immediately seen a remarkable uptick in in-app feedback from that region. At this point, we haven’t even started to solve the problem at hand, but we have already begun to build a legion of power-users who will provide honest feedback when we release something good or bad; all because they now see we’re real humans.

Research Pt. 2: Frequent Check-Ins with Users

Once our minds are swirling with ideas from big stores, small stores, stores with mature processes, and stores who yearn for a more efficient process, we start iterating on a prototype. We engineers, our product manager, and our designer all work together on validating this design (not just our designer!) and we are quick to reach back out to stores (in-person or over chat) to challenge assumptions. I can’t overstate this part of the process enough - this is the real secret sauce that allows our team to work in a truly agile way. It would be all too easy to fall into a waterfall pattern of collecting requirements from users in the initial tour and then never talk to them again until release time. Don’t do this!!

Throughout the months of building the Price Change Tool, we had barely a week go by where at least one of us wasn’t in a store talking to users. This process meant that by the time we launched, we had a handful of users in 3-4 stores who had seen every major iteration of the design throughout the development process.

Bonus: Standard Operating Procedures

In the past, we haven’t always done a good job at releasing a standard operating procedure (SOP) with our new tools. This leads our 150+ stores to develop 150+ ways of using the tool… with varying levels of success. Other times, our continuous-improvement (CI) partners would later write an SOP that works with the tool… even if the tool doesn’t support the most efficient way of completing a task. With the Price Change Tool, we tried something a little less waterfall - we embedded one of our CI partners directly into our product team. They joined for our daily standups, the listening tour, story refinement sessions, and had an active voice in deciding how we would build this tool.

The lesson we learned: we’re going to do this for all future tools we build. As we release this tool to the entire enterprise, we can refer our users to a cohesive SOP that was built hand-in-hand with the tool. We have built the tool to flow in a way that encourages users to follow the SOP and intentionally added carefully placed tooltips throughout the app to ease the transition from paper to digital tool.

The Solution Pt. 1: Pilot Releases

We’ve spent months building this tool, we’re as sure as we can be that it’s going to work, so time to let it rip across all our stores? Nope!

Over the last few years, our team has developed a carefully crafted pilot program. For smaller releases, we release the app to a handful of stores, let it bake for a week, build any show-stoppers into a hot-fix release or the enterprise release, and then we release to the enterprise. For bigger releases, like the Price Change Tool, we have developed a multiphase pilot plan.

Phase 1: We release the tool to a handful of stores, with a member of our team in each store. (*while constantly iterating on feedback*)
Phase 2: We release the tool to more stores, including stores from the listening tour, and other stores within the vicinity of our team members, so they can be in-store. (*while constantly iterating on feedback*)
Enterprise go-live: let it rip!

This multiphase approach allows us ample time to iterate on backend and frontend changes, tweak the SOP, and see how users react to the tool.

It’s sometimes difficult to know if a user pain-point is a real long-term issue, or just a side effect of transition, but building the tool alongside our users gives us some unique insight into that problem. Since we have some users that have seen this tool for months (as we’ve built it), and some users that see it for the first time on day one of the pilot, we have some data to draw on as we try to make this distinction.

This pilot approach also gives our team a real chance to use the tool. We intentionally scheduled the pilots to include days with lots of price changes, so we can get in the store and feel how frustrating it is to do flow X or how nice it would be to have improvement Y.

The Solution Pt. 2: Rapid Iteration

It is a little odd that this entire engineering blog post hasn’t had any reference to code yet… don’t worry! There’s a lot of cool innovation that went into delivering a tool that gives us flexibility in responding to feedback after we go live in stores. But as this post is already quite long, I am going to post that in a separate blog entry on server-driven design. Stay tuned!

The Good Part

So why does this process matter? Why am I writing this post at all?

My hope is that this story inspires even a single internal-facing product team to change their ways of working to bring their users radically deep into the development process. I truly believe this process results in employees being more satisfied (or at least less frustrated) with their jobs, less production issues in tools, and a better developer experience.

But as for me, when I look back on this entire build, the coolest part of all of this boils down to a single moment that came on the first big price change day in Phase 1 of our pilot release.

It was the end of the day, and I found myself and 4 green-vests crammed in a small room in the back office of the Roseville, CA store (shout-out to the awesome folks at store 74!). We were all tired, half of us sitting on the floor, having all spent a considerable part of our day using the tool, debugging issues, and creating lists of things that we thought really needed to be changed before the enterprise go-live. Even though we were all exhausted, that conversation was at least as in-depth as any story refinement session we’ve ever had as a product team. I was furiously taking incoherent notes on my laptop as ideas were flying left and right about how to fix issues, streamline workflows, and add net-new features none of us had considered before. The store employees truly had a seat at the table to make decisions about the tool we would release a couple of weeks later to the entire company.

That moment warms my heart not just because I’m a developer that gets the privilege to build cool stuff alongside my users, but because I started my career at REI as a green-vest. I remember being in their shoes, frustrated about an out-dated tool/process that feels like it may never change. I remember the first time I talked to a real person from REI IT, and the hope that it brought me that we could make things better. And now, here I am, still working shoulder-to-shoulder with my fellow green-vests, building solutions to real problems that affect thousands of real people every day.

XCUITest Automation: Page Components for iOS Test Automation

2024-01-29T00:00:00+00:00

Creating Stable, Maintainable User Interface Test Automation in Swift

When creating test automation to validate the performance and behavior of a complex software application, adhering to solid engineering practices will produce stable, maintainable tests. This is especially true when driving the application through its user interface. Page Object Model (POM) design patterns provide a solid framework to achieve this objective.

Functional grouping with page components

In the previous article, we showed how POM design patterns can be applied to implementing automated interactions with iOS applications through the XCUITest framework. Modeling each view with a single comprehensive page class is adequate for simple views, but factoring the features of more complex view into functional grouping can simplify interactions with these features.

Modeling an application based solely on its views produces a very flat model. It’s quite common for a view to contain groups of elements that are logically associated (e.g. - billing address on an order information view). It’s also common to encounter views with multiple occurrences of an element grouping (e.g. - item tiles on a search results view). Factoring these grouping out into page components can greatly enrich your models, presenting a conceptual framework that automation developers will recognize.

In the following example, the title block elements of the product details view are modeled in a page component:

ProductDetailsView excerpt

//
//  ProductView.swift
//  Copyright © 2024 REI. All rights reserved.
//

import XCTest

class ProductDetailsView<T: BaseView>: NavigationHub {
    lazy var titleBlock: ProductTitleBlock = {
        return ProductTitleBlock(self)
    }()
    
    // -._.-'¯'-._.-'¯'-._.-'¯'-._.-'¯'-._.-'¯'-._.-'¯'-._.-'¯'-
}

ProductTitleBlock

//
//  ProductTitleBlock.swift
//  Copyright © 2024 REI. All rights reserved.
//

import XCTest

class ProductTitleBlock<T: BaseView> {
    enum Element {
        case product_brand
        case product_title
        case style_or_sku
        
        func locator(_ context: XCUIElement) -> XCUIElement {
            switch self {
            case .product_brand:
                return context.staticTexts["TitleBlock.productBrand.label"]
            case .product_title:
                return context.staticTexts["TitleBlock.productName.label"]
            case .style_or_sku:
                return context.staticTexts["TitleBlock.styleOrSku.label"]
            }
        }
    }
    
    private let parent: T
    
    init(_ parent: T) {
        self.parent = parent
    }
    
    func getProductId() -> String {
        return Element.style_or_sku.locator(parent.APP).label
    }
}

In the preceding code, note how the ProductTitleBlock page component is defined as a lazy-initialize property of the main ProductDetailsPage class. The page component itself declares a locator enumeration that defined three title block elements, with the getProductId() function providing access to the corresponding content.

Note that the context used to locate the product ID element is derived from the component’s parent (the product details view). In this case, the search context for component elements is the target application, because there’s no specific container that groups the title block elements. However, it’s common for components to represent specific sub-contexts - a scroll view for a multi-item collection or a cell that contains one of these items. More on search contexts and component collections later.

The test class shown below demonstrates an how an automated test might use this page model to verify that the expected product ID is shown in the title block of the product details view.

class MSAProductTabTests: XCTestCase {
    
    func testSKUShownOnPDP_NoColor_NoSize() {
        let sku = "510-145-0012"
        guard nil != ascentHomeView.launchTheApplication() else { return }
        guard let productDetailsView = ascentHomeView.searchBar.searchForSingleItem(sku) else { return }
        XCTAssertEqual(productDetailsView.titleBlock.getProductId(), sku, "Did not find product SKU: \(sku)")
    }
}

As shown above, access to the product ID is provided by the ProductTitleBlock page component via the [titleBlock] property of the ProductDetailsView object. The logical grouping provided by this structure helps to differentiate the features of this group relative to other components of the view. This can be extremely helpful when implementing tests that interact with complex views comprised of dozens of elements. Each component provides focused access to a small set of logically associated elements, while a flat model would inundate the test author with an unstructured collection of every element of the entire view.

Page component with unique search context

The ProductTitleBlock page component model shown above illustrates a “virtual component” - a page component with no associated container element. These sorts of components are great for organizing and logically segmenting the functionality of complex views. The presence of a unique container element that encapsulated the features of a page component can increase the cohesion, safety, and efficiency of your model by providing a limited scope for element selection - the search context.

The following example demonstrates how to define and use a pre component search context:

Defining search context for singleton page component

//
//  ProductInventoryBlockSubView.swift
//  MSAMobileApp-UITests
//
//  Created by John Comstock on 8/2/21.
//  Copyright © 2021 REI. All rights reserved.
//

import XCTest

class ProductAvailabilityHeader<T: NavigationHub> {
    
    enum Element {
        case view_context
        case onhand_value
        
        func locator(_ context: XCUIElement) -> XCUIElement {
            switch self {
            case .view_context:
                return context.otherElements["AvailabilityHeader.container.element"]
            case .onhand_value:
                return context.staticTexts["OnHand.availability.value"]
            }
        }
    }
    
    private let parent: T
    private let context: XCUIElement
    
    init(_ parent: T) {
        self.parent = parent
        self.context = Element.view_context.locator(parent.APP)
    }

    func getNearbyQuantity() -> String {
        return Element.nearby_value.locator(context).label
    }
}

Note that the initializer receives a reference to the page or component that’s including the ProductAvailabilityHeader component - the parent. The initializer derives the component’s search context from the parent, and this becomes the context for element searches within the component itself. For example, the getNearbyQuantity() function derives the locator to the nearby store quantity element relative to this context.

It’s not uncommon for page components to be initialized with a pre-assembled search context. However, this distributes the responsibility for defining and handling the attributes and behaviors of the component to two different classes - the page component and its parent. Prefer confining all component-specific operations to the page component class itself. This increases cohesion and simplifies ongoing maintenance of the page model implementation.

Search context for page component collection entries

Search contexts aren’t required to be unique. It’s commonplace to encounter multiple inherently indistinguishable container elements that encapsulate functionally equivalent components (e.g. - search result items). When modeling these sorts of components, definitive identification of each component must typically derive from attributes of elements within the component. Ideally, however, each container element will provided a unique identifier. In the following example, the style identifier for the product presented in each search result component is stored in the [value] property of the containing cell element:

Defining unique search contexts for page component collection entries

//
//  SeaarchResult.swift
//  Copyright © 2024 REI. All rights reserved.
//

import XCTest

class SearchResult<T: BaseView> {
    enum Element {
    case result_cell(String? = nil)
        case product_brand
        
        func locator(_ context: XCUIElement) -> XCUIElement {
            switch self {
            case .result_cell(let id):
                if let styleId = id {
                    let predicate = NSPredicate(format: "identifier == %@ AND value == %@", SearchResultConstants.RESULT_CELL, styleId)
                    return context.cells.matching(predicate).element
                }
                return context.cells[SearchResultConstants.RESULT_CELL]
            case .product_brand:
                return context.staticTexts["SearchResultCell.productBrandLabel"]
            }
        }
    }
    
    private let parent: T
    private let styleId: String
    private let context: XCUIElement
    
    init?(_ context: XCUIElement, in parent: T) {
        guard let styleId = context.value as? String else {
            XCTFail("Failed extracting style ID from search result cell value")
            return nil
        }
        
        self.parent = parent
        self.styleId = styleId
        self.context = Element.result_cell(styleId).locator(parent.APP)
    }
    
    func getProductBrand() -> String {
        return Element.product_brand.locator(context).label
    }
    
    static func buildResultsList(_ parent: T) -> [SearchResult<T>]? {
        let selector = Element.result_cell().locator(parent.APP)
        guard selector.waitForExistence(timeout: Constants.standardTimeout) else {
            XCTFail("Failed to load Search Results")
            return nil
        }

        var searchResults: [SearchResult<T>] = []
        for element in selector.allElementsBoundByAccessibilityElement {
            guard let searchResult = SearchResult(element, in: parent) else {
                return nil
            }
            searchResults.append(searchResult)
        }
        return searchResults
    }
}

struct SearchResultConstants {
    static let RESULT_CELL = "SearchResult.cell"
}

The SearchResult class provides a static function that builds a collection of search result page components. Note how the buildResultsList() function employs the no-argument form of the result_cell constant to acquire a list of every search result container element in the view. The implementation iterates over the selected container elements via their accessibility identifiers, which are somewhat more durable than the references produced by allElementsBoundByIndex. However, these references are still at risk of going stale when the view gets repopulated after the search results are scrolled or filters are applied.

To avoid subsequent reference mismatch issues, the SearchResult initializer produces a fully qualified reference by specifying the style ID as the argument for the result_cell element locator constant. This ensures that we always select the search result we expect. If the specified element exists, the associated search result item is guaranteed to show the expected product. If the specified element isn’t found later (e.g. - excluded by an applied filter), we can be certain that the corresponding search result item is actually gone. Note that the initializer is specified as optional; if the style ID can’t be acquired with the specified element reference, the initializer returns nil. (This is academic, though, since the initializer also registers a test failure.)

Summary

Page object design patterns provided many benefits when applied to user interface automation of iOS applications. Modeling related groups of elements as page components can make your designs even more cohesive, comprehensible, and flexible. The logical encapsulation provided by page components can reduce the complexity of implementing and interacting with the associated application features. This is especially true for views that contain multiple instances of the same component.

Written with StackEdit.

XCUITest Automation: Page Object Models for iOS Test Automation

2024-01-26T00:00:00+00:00

Creating Stable, Maintainable User Interface Test Automation in Swift

Implementing Page Object Model (POM) patterns in Swift

Page Object Model (POM) design patterns, originally conceived to automate web application user interface tests, can be applied to testing iOS application through the XCUITest framework. Following a page-model approach produces structured interfaces that your tests can use to drive the target application and verify expected behaviors.

Each application main view is associated with a separate page model class.
Functions that trigger navigation wait for the expected landing view to appear and return an instance of the corresponding page model class.
To facilitate navigation rewinding, stackable page model classes are parameterized, with the type parameter supplying the return type for back/close operations.
Groups of elements that comprise distinct units of application functionality can be modeled as page component classes.
Repeated element groupings (e.g. - search result items) should be modeled as page component collections.
Define element locators in Swift enumerations to avoid duplication of element types and attributes.

Synchronization - The lynchpin of stable automation

In user interface automation, everything begins and ends with definite synchronization between the application under test (AUT) and the automation that drives it. This isn’t just a figure of speech; it’s literally true.

Before interacting with a view that’s just been opened, perform load-completion checks to ensure that the application is ready for action.
After performing an action that triggers an application state change (expanding a dropdown, opening a modal, etc.), wait for the expected response.

Adhering to these rules ensures that your automation interacts smoothly and reliably with the application. It also enables you to recognize unexpected behavior at the point where it’s encountered, failing with clear diagnostic output indicating what went wrong. Remember…

RULE #1: Fail Fast with Detailed Diagnostics

The SynchronizedView protocol

In the REI automation framework, all of our application view page models implement a SynchronizedView protocol. The methods that facilitate page load synchronization are:

waitForView(required: Bool) -> Self? Wait for the view associated with this model to finish loading.
checkViewCriteria() -> String? Determine if all evaluated criteria indicate that the view associated with this model has finished loading.
hasNetworkSpinner() -> Bool Determine if transition to the view associated with this model initially displays a network activity spinner.
launchTheApplication() -> Self? Launch the target application and wait for the expected view to load.

The foundation of the synchronization provided by the framework is the checkViewCriteria() function. Each page class declares a view-specific implementation of this function. As described in the function header, the implementation returns nil when all evaluated criteria are met. If any evaluated criterion is unmet, the function returns a string that describes the issue. If after twenty seconds the function doesn’t return nil, the affected test is terminated with the description of the unmet criterion.

NOTE: The checkViewCriteria() function should perform instantaneous evaluations; it should check for each defined criterion and return immediately upon encountering one that’s not met. The implementation of waitForView() polls this function repeatedly until it returns nil or the maximum delay interval has elapsed.

Page Object Model Protocol (Part 1 - Synchronization)

//
// SynchronizedView.swift (Part 1)
// Copyright © 2024 REI. All rights reserved.
//

import  XCTest

protocol  SynchronizedView {
    /// Determine if transition to the view associated with this model initially displays a network activity spinner.
    /// > Note: The default implementation of this function returns `false`; declare an override returning `true` if the associated view opens with a spinner.
    /// - Returns: `true` if expecting an initial network spinner
    func  hasNetworkSpinner() -> Bool

    /// Determine if all evaluated criteria indicate that the view associated with this model has finished loading.
    /// - Returns: `nil` if all evaluated criteria are satisfied; otherwise, description of unsatisfied view load criterion
    func  checkViewCriteria() -> String?

    /// Launch the target application and wait for the expected view to load.
    /// - Returns: this view model; `nil` if expected view doesn't load
    func  launchTheApplication() -> Self?

    /// Terminate the target application.
    func  terminateTheApplication()

    /// Wait for the view associated with this model to finish loading.
    /// > Note: If ``hasNetworkSpinner()`` returns `true`, this function will wait for the network spinner to vanish prior to evaluation of view load criteria.
    /// > Note: If [required] is `true` and the standard load interval expires, the current test will fail with a message indicating this model and the description of the unsatified view load criterion.
    /// - Parameter required: [optional] `false` if incomplete loading of the associated view is allowed (default = `true`)
    /// - Returns: this view model; `nil` if view transition fails
    func  waitForView(required: Bool) -> Self?
}

extension  SynchronizedView {
    func  waitForView(required: Bool = true) -> Self? {
        if  hasNetworkSpinner() {
            // TODO: application-dependent spinner check
        }

        if  let result = Utility.waitForExpression(checkViewCriteria(), timeout: Constants.standardTimeout) {
            if  required { Utility.failWithAlertCheck("Failed opening '\(getViewName())' view: \(result)") }
            return  nil
        }
        return  self
    }
}

The navigation strategy employed by the REI automation framework explicitly defines the relationships between associated views:

Every method that triggers a view transition returns an instance of the page class for the expected landing view.
To facilitate retracing steps in the navigation stack, each page object retains the instance that spawned it (the origin).
Each navigation stack originates from a root view, which has no origin.
Non-root page classes are parameterized, and the parameter type specified when each instance is created resolves the class of the origin when stepping back down the stack.

The first point of this strategy is the key to effortless stability at view transitions. When your model returns a new page object, the framework has already ensured that the corresponding view is present and prepared for the next action. This is accomplished in openView() and returnToOrigin() via the waitForView() function, which uses the checkViewCriteria() function of the new page object for synchronization.

Page Object Model Protocol (Part 2 - Object Chaining)

//
// SynchronizedView.swift (Part 2)
// Copyright © 2023 REI. All rights reserved.
//

import  XCTest

protocol  SynchronizedView {
    /// Origin of this view.
    /// > Note: The origin is the view that the application returns to when the user taps **Back** or **Close**; may be `nil`
    var origin: BaseView? { get }

    /// Target application for this view.
    var APP: XCUIApplication { get }

    /// Required constructor:
    /// - Parameters
    /// - origin: [optional] Origin of this view (default = `nil`)
    /// - app: Target application for this instance
    /// - See: ``origin``
    init(_  origin: BaseView?, app: XCUIApplication)

    /// Open the indicated view by tapping the specified element.
    /// > Note: If [required] is `true` and the standard load interval expires, the current test will fail with a message indicating this model and the description of the unsatified view load criterion.
    /// - Parameters:
    /// - viewType: Class of the automation model associated with the view that opens after tapping the specified element
    /// - targetApp: [optional] Target application for view being opened (default = `self.APP`)
    /// - element: Element that triggers the expected view transition
    /// - fixed: [optional] `true` if the specified element is non-scrollable (default = `false`)
    /// - required: [optional] `false` if incomplete loading of the associated view is allowed (default = `true`)
    /// - Returns: target view model; `nil` if view transition fails
    /// - See: ``waitForView``
    func  openView<T: BaseView>(_  viewType: T.Type, targetApp: XCUIApplication?, byTapping  element: XCUIElement,
                                fixed: Bool, required: Bool) -> T?

    /// Tap **Back** / **Close** to navigate back to the origin of the current view, as registered in this model.
    /// > Note: This function is unsupported for "navogation hub" models, as these represent the bottom of the nav stack and therefore have no related **Back** action.
    /// - Parameters:
    /// - element: [optional] Element that triggers the expected view transition (default = `nil`)
    /// - fixed: [optional] `true` if the specified element is non-scrollable (default = `false`)
    /// - required: [optional] `false` if incomplete loading of the associated view is allowed (default = `true`)
    /// - Returns: origin view model; `nil` if view transition fails
    /// - See: ``origin``
    func  returnToOrigin<T: BaseView>(byTapping  element: XCUIElement?, fixed: Bool, required: Bool) -> T?
}

Best practices for stable automation models

The REI framework implements several patterns that promote stable, reliable operation of our user-interface test automation. The full benefits of these facilities rely on the proper implementation of protocol functions within the page classes.

Use the openView() and returnToOrigin() functions for all view transitions:

  func  openKnowledgeBase() -> KnowledgeBaseHome<SettingsHomeView>? {
      return  openView(KnowledgeBaseHome<SettingsHomeView>.self, byTapping: Element.knowledge_base_link.locator(APP))
  }

Perform explicit synchronization after each action that triggers a state transition (e.g. - switch filter mode):

  func  switchMode(via  element: Element) {
      let reference = element.locator(APP)
      if !reference.isSelected {
          reference.tap()
          reference.wait(until: \.isSelected)
          guard reference.isSelected else {
              XCTFail("Filter mode failed to become selected")
              return
          }
      }
  }

NOTE: Each of these examples ensures that the transition is complete and the application is in the expected state before returning to the caller. This practice, called exit-state synchronization, is far more efficient and reliable than adding synchronization at the beginning of down-stream functions.

Best practices for test implementation

Adhering to a few core practices affords your tests the greatest benefit from the synchronization and stability provided by the REI framework:

Only the initial page object is instantiated directly by the tests, typically in the setupWithError() function.
All other page objects are returned by functions that trigger view transitions.
Use the guard let pattern to resolve the optional page object values returned by transition-triggering functions.

The example test class shown below demonstrates these practices. Note that the test code doesn’t require explicit verification of landing views at transitions, because the model does this automatically.

import  XCTest

class  MSABasicNavigationTests: XCTestCase {
    private  var ascentHomeView: AscentHomeView!

    override  func  setUpWithError() throws {
        ascentHomeView = AscentHomeView(app: XCUIApplication.testingApp)

        // stop immediately on failure
        continueAfterFailure = false
    }

    override  func  tearDownWithError() throws {
        ascentHomeView = nil
    }

    func  testNavigationToAscentKnowledgeBase() {
        guard  nil != ascentHomeView.launchTheApplication() else { return }
        guard  let settingsHomeView = ascentHomeView.footerBar.selectSettingsTab() else { return }
        guard  let ascentKnowledgeBase = settingsHomeView.openKnowledgeBase() else { return }
        guard  nil != ascentKnowledgeBase.backToOrigin() else { return }
    }
}

The preceding example demonstrates the page object chaining behavior of the framework. The output of each function that triggers a view transition is the page object for the view that was activated by the function. If a nil is returned, the test exits immediately. Because we set continueAfterFailure to false during test setup, this is academic - an error has already been registered explaining the issue. However, it’s still a good practice.

Handling transitions with interstitial “toast”

When an action triggers a view transition that also includes a “toast” message, special handling is required to capture and respond to the “toast” message and synchronize with the newly activated view. These events must be handled within the context of a single function; Attempting to handle the “toast” message separately is far too likely to result in unreliable synchronization. The REI framework provides two functions that encapsulate the handling of transitions with “toast”:

    /// Open the indicated view by tapping the specified element, waiting for an expected "toast" message and performing the action it presents.
    /// > Note: If [required] is `true` and the standard load interval expires, the current test will fail with a message indicating this model and the description of the unsatified view load criterion.
    /// - Parameters:
    /// - viewType: Class of the automation model associated with the view that opens after tapping the specified element
    /// - originType: [optional] Class of landing view model if back/close of target view performs unlinked navigation (default = `nil`)
    /// - element: Element that triggers the expected view transition
    /// - fixed: [optional] `true` if the specified element is non-scrollable (default = `false`)
    /// - required: [optional] `false` if incomplete loading of the associated view is allowed (default = `true`)
    /// - Returns: **TransitionWithToast()** object containing target view model and "toast" information; object with default values if view transition fails or "toast" isn't found
    /// - See: ``waitForView``
    /// - See: ``TransitionWithToast``
    /// - See: ``ToastInfo``
    func  openViewWithToastAction<U: BaseView>(_  viewType: U.Type, originType: BaseView.Type? = nil, byTapping  element: XCUIElement,
                                               fixed: Bool = false, required: Bool = true) -> TransitionWithToast<U>

    /// Tap **Back** / **Close** to navigate back to the origin of the current view, as registered in this model, waiting for an expected "toast" message and performing its action if specified.
    /// > Note: This function is unsupported for "navigation hub" view models, as these represent the bottom of the nav stack and therefore have no related **Back** action.
    /// - Parameters:
    /// - element: Element that triggers the expected view transition
    /// - fixed: [optional] `true` if the specified element is non-scrollable (default = `false`)
    /// - required: [optional] `false` if incomplete loading of the associated view is allowed (default = `true`)
    /// - performAction: [optional] `true` if the action presented by the "toast" message should be performed (default = `false`)
    /// - Returns: **TransitionWithToast()** object containing target view model and "toast" information; object with default values if view transition fails or "toast" isn't found
    /// - See: ``origin``
    /// - See: ``waitForView``
    /// - See: ``TransitionWithToast``
    /// - See: ``ToastInfo``
    func  returnToOriginWithToast(byTapping  element: XCUIElement, fixed: Bool = false,
                                  required: Bool = true, performAction: Bool = false) -> TransitionWithToast<T>

ToastInfo

struct  ToastInfo {
    let message: String
    let identifier: String
    let hasAction: Bool
}

TransitionWithToast

struct  TransitionWithToast<T> {
    let view: T?
    let toastInfo: ToastInfo?

    init(view: T? = nil, toastInfo: ToastInfo? = nil) {
        self.view = view
        self.toastInfo = toastInfo
    }
}

As indicated, the preceding functions handle view transitions that include the appearance of interstitial “toast” messages. The return values of these functions (TransitionWithToast) encapsulate the view model and a “toast” information (ToastInfo) object. These are the potential outcomes:

If the expected view activates, a reference to the view model is returned in the [view] property.
If the expected view doesn’t activate, the [view] property will be set to nil.
- NOTE: If the [required] argument of the function call is true (the default value), a test failure will be registered.
If a “toast” message appears, a ToastInfo object is returned in the [toastInfo] property containing the message text, identifier, and action.
If no “toast” message appears, the [toastInfo] property will be set to nil.
- NOTE: No test failure is registered.
The test itself must determine whether the returned “toast” information (or lack thereof) meets expectations.

The following demonstrates the application of openViewWithToastAction() to tap an element and perform the navigation provided by the “toast” message:

    func addLabelAndOpenPrintBasket() -> TransitionWithToast<PrintBasketView> {
        let optionsSheet = Element.options_sheet.locator(APP)
        let selector = Element.add_label.locator(optionsSheet)
        return openViewWithToastAction(PrintBasketView.self, originType: ToolsHomeView.self,
                                       byTapping: selector, fixed: true)
    }

Note that the “origin” type is specified here. This isn’t always required, but the origin of the Print Basket is the Tools Home view, not the “quick print” menu. Here’s an example of a test that uses this function:

    func testPrintOptions_PrintBasket() {
        let sku = "2028570010"
        guard nil != ascentHomeView.launchTheApplication() else { return }
        guard let productDetailsView = ascentHomeView.searchBar.searchForSingleItem(sku) else { return }
        guard let quickPrintMenu = productDetailsView.tapPrintingOptionsButton() else { return }
        let transition = quickPrintMenu.addLabelAndOpenPrintBasket()
        guard let printBasketView = transition.view else { return }
        XCTAssertEqual(transition.toastInfo?.message, "1 label added Print Basket", "Toast message mismatch")
        XCTAssertEqual(printBasketView.getPrintBasketItemCount(), 1, "Print basket item count mismatch")
        guard nil != printBasketView.backToToolsHome() else { return }
    }

This test opens a product page by searching for a SKU, opens the “quick print” menu, adds a label, and opens the print basket via the “toast” action. Synchronization and verification are performed at every step.

Summary

Applying Page Object Model (POM) patterns to the implementation of XCUITest automation produces well-structured interfaces that are rational and maintainable. Ubiquitous definite synchronization between your tests and the target application ensure reliable, efficient execution. Utilization of framework-supported linked navigation with automatic page-load verification ensures that you always land where you expect - or fail immediately when you don’t. Following the “fail fast with detailed diagnostics” rule eliminates much of the ambiguity that can otherwise make the process of investigating test failures frustrating and time-consuming.

Written with StackEdit.

XCUITest Automation: Encapsulating Element Locators in Swift Enumerations

2023-11-29T00:00:00+00:00

Creating Stable, Maintainable User Interface Test Automation in Swift

In user-interface automation, following a page-model approach provides a structured interface that your tests can use to drive the target application and verify expected behaviors. A foundational feature of any user-interface automation strategy is a mechanism to locate and interact with the elements of the interface - buttons, input fields, descriptive text, et cetera.

Apple’s user-interface automation framework for driving iOS application is XCUITest. This framework provides a rich set of classes, properties, and enumerations from which to specify the characteristics of target elements. To produce cohesive models that encapsulate all the details of your element locators, consider Swift enumerations.

Defining element locators in Swift enumerations

Two common issues that complicate the usage and maintenance of any programming interface are duplicate definitions of constant values and incomplete declarations that require additional context to be used. Each of these characteristics presents challenges when the definitions of associated elements in the target application change, because you’re forced to track down all of the related definitions and apply the same revisions everywhere.

To avoid these sorts of issues, declare element locators in a comprehensive Swift enumeration in the view or component class that’s responsible for interacting with the corresponding elements. For example:

enum Element {
    case view_title
    case refine_view(String)
    case facet_label(String? = nil)
    case filter_cell(String? = nil, String? = nil)
    
    func locator(_ context: XCUIElement) -> XCUIElement {
        switch self {
        case .view_title:
            return context.navigationBars[rawValue]
        case .refine_view:
            return context.collectionViews[rawValue]
        case .facet_label(let name):
            if let nameOrKey = name {
                let predicate = NSPredicate(format: "identifier == %@ AND (label == %@ OR value == %@)",
                                            rawValue, nameOrKey, nameOrKey)
                return context.staticTexts.matching(predicate).element
            }
            return context.staticTexts[rawValue]
        case .filter_cell(let facet, let filter):
            if let facetKey = facet, let filterName = filter {
                let cellPredicate = NSPredicate(format: "identifier == %@ AND value == %@", 
                                                rawValue, facetKey)
                if filterName.isEmpty {
                    return context.cells.matching(cellPredicate)
                        .containing(.staticText, identifier: Self.Constants.FILTER_LABEL.rawValue).element
                } else {
                    let labelPredicate = NSPredicate(format: "identifier == %@ AND label BEGINSWITH %@",
                                                     Self.Constants.FILTER_LABEL.rawValue, filterName)
                    return context.cells.matching(cellPredicate).containing(labelPredicate).element
                }
            }
            return context.cells[rawValue]
        }
    }
    
    var rawValue: String {
        switch self {
        case .view_title:
            return "Search Filter"
        case .refine_view(let name):
            return name
        case .facet_label:
            return "RefineSearch.filterFacet.label"
        case .filter_cell:
            return "RefineSearch.filterName.cell"
        }
    }
    
    enum Constants: String {
        case FILTER_LABEL = "RefineSearch.filterName.label"
    }
}

The preceding declaration defines a locator function, a rawValue computed property, a nested Constants enumeration, and four element locator values:

A simple locator for an element with a constant identifier…
- … produces a constant context-relative element locator.
A parameterized locator with a single required associated value…
- … produces context-relative element locators based on the specified value.
A parameterized locator with a single optional associated value…
- … [value omitted] produces a constant context-relative locator that finds multiple matching elements. … OR …
- … [value defined] produces context-relative locators based on the defined value that find unique elements.
A parameterized locator with a pair of optional associated values…
- … [values omitted] produces a constant context-relative locator that finds multiple matching elements. … OR …
- … [first defined, second empty] produces context-relative locators based on the defined value that finds multiple matching elements. … OR …
- … [both defined] produces context-relative locators based on the defined values that find unique elements.

Note that the locator function requires a “context” argument. This is the search context for the returned element locator. The element locator values produced by locator acquire the identifiers they need from the rawValue computed property. Associated values are declared or omitted in each context (locator or rawValue) as needed.

The “context” argument will typically be the “application” object, which will search the entire view hierarchy. To find elements within a sub-context, provide this instead:

func setFilter(_ filter: String, in facet: String, of refinement: String) {
    let refineView = Element.refine_view(refinement).locator(XCUIApplication())
    let filterElem = Element.filter_cell(facet, filter).locator(refineView)
    if !filterElem.isSelected { filterElem.tap() }
}

In the preceding example, the “application” object is the context of the “refine” view locator, which defines the context for the “filter” element locator.

NOTE: For simple cases, localized handling of sub-contexts like the “refine” view does the trick. When modeling more complex sub-contexts with multiple associated elements and related behaviors, the use of component classes can provide cleaner, more maintainable designs. The details of this structure are documented here.

The nested Constants enumeration is used to define constant value that are used multiple time within the Element enumeration, but are not associated with a defined element locator value. This “constants enumeration” pattern ensures that each value is defined only once, avoiding the risk of retaining stale copies when value updates are needed.

Summary

The encapsulation of element locators in comprehensive Swift enumerations can eliminate the confusion and inconsistencies that bedevil other approaches. By defining all aspects of each target element in a single place, the task of debugging and maintaining element locators is greatly simplified. With context scoping and associated values, each locator enumeration constants can provide selectors with graduated levels of specificity - from global all-of-type matching to context-constrained unique-instance matching.

Note regarding another enum-based locator definition strategy

While preparing to write this article, I performed a search to determine if others have described similar strategies. I found this article by Nishith Shah, which begins with the same basic approach I used. As this strategy is developed through the article, a few key differences emerge:

While the use of raw values solves the issue of duplicated constant declarations, this choice precludes the use of associated values which greatly enhance the expressiveness of locators for element collections. While these can be modeled via nested components, this level of factoring often results in a proliferation of tiny classes with limited functionality which are difficult to debug and maintain.
The rawValue computed property demonstrated in the example above also avoids duplicated constant declarations, with the added benefit that the resulting identifiers can incorporate specified associated values.

Grouping elements by type and handling them in a generic fashion increases complexity and makes the code harder to maintain. The apparent repetition incurred by handling each case independently eliminates the risk of breaking cases you weren’t intending to change when updating cases that require change.

The use of a computed property instead of a function to generate locators precludes the option of providing a search context. While this context is often the application under test, it may also be the root element of a component model (e.g. - an item in a table view). It might also be an entirely different application, such as Safari or Springboard (which is used to access elements in the status bar).

Written with StackEdit.

Switching Trails to SwiftUI: Our Journey at REI

2023-10-17T00:00:00+00:00

Declarative vs. Imperative Programming

When providing instructions for packing a backpack in an imperative framework, you would list each of the ten essentials and provide exact instructions on locating each item and fitting them all nicely within your pack. In a declarative framework however, you don’t need to meticulously outline these steps. You can instead define the result — a backpack packed with these ten items. The system then figures out how to obtain and fit them in the pack.

This of course, requires you to trust the system to choose the right items and arrange them correctly.

When it comes to computer programming, often there’s little doubt the system will do what you expect. Higher order functions like ‘map’, ‘reduce’ and ‘filter’ give us a taste of declarative programming. Rather than explicitly looping through an array and manipulating data, you can use these methods to declare what you want done and the system will perform the desired manipulation to each element.

The declaritive version of these simple list manipulations is half the length as the imperative version, and easier to follow.

When it comes to user interfaces however, there is much more ambiguity in the desired outcome. With that ambiguity comes a reluctance to relinquish control. Can you really trust the system to size things correctly on different form factors without explicit instructions? Will a long list scroll performantly without giving detailed instructions on how and when to create new views versus simply reusing old ones?

Declarative UI frameworks say yes and have been rising in popularity. In 2019 Apple put out their own declarative UI framework — SwiftUI.

Deciding to Declare

Like most iOS developers, we approached SwiftUI with some trepidation here at REI. The framework is still evolving and unlike longer lived frameworks, the answers to questions that arise might not yet be chronicled on StackOverflow. The benefits however are clear. The concise, descriptive SwiftUI code makes maintaining, refactoring, and reusing components much simpler than it was before. It also seems clear that it’s Apple’s preferred framework, with components such as Home Screen Widgets requiring SwiftUI. Navigating the SwiftUI learning curve seems inevitable for iOS development, it’s only a question of when.

With this in mind, we recently decided to move to SwiftUI for our retail employee app, Ascent. This was an easier decision for this app than most, as we have the luxury of owning the devices the app is deployed on. We can ensure everyone is on the latest iOS version, allowing us to use latest and greatest features of SwiftUI as they become available. The roadmap for the app also lended itself nicely to an overhaul. As we continued to add features to the app, it required a redesign of the fundamental navigation structure. This was the perfect opportunity to build a foundation of SwiftUI.

Navigating the Move to SwiftUI

We planned for all new development to be in SwiftUI, and to refactor existing screens to SwiftUI when meaningful changes need to be made. To set ourselves up for success, we adopted a SwiftUI architecture that would make refactoring existing UIKit screens as painless as possible.

Our UIKit architecture follows the Model, View, Presenter. (MVP) pattern. These presenters contain the business logic that setup the data (model) needed to a particular screen (view), and then communicates the necessary updates to the view. The communication between presenter and view are backed by protocols, allowing mock views for easy unit testing.

When refactoring an existing UIKit using MVP to SwiftUI, we were able to keep the presenters largely unchanged. The view however is replaced by a new SwiftUI view object, composed of one or many subviews. Each subview defines a ViewModel for anything that can change in it. Then, we can add these ViewModel objects as @Published properties to our presenters, and reference them as @State properties in the top level SwiftUI view. Instead of presenter invoking the protocol methods on the view, we simply update the viewModels to the desired state when appropriate. This ends up looking a lot like a Model, View, ViewModel architecture.

Our AscentSection component, its use in the ToolsPresenter as @Published properties, and resultant screen.

The result is very clean and modular view code that naturally lends itself to reusable components. We also retain testability for the business logic in our presenters. Instead of setting up mock views, we simply observe the @Published properties in each presenter and listen for the expected updates.

Developing in this environment can be a joy. Instead of being bogged down by boilerplate code and view lifecycles, one can focus on what really matters-— the look and feel of the app and the associated business logic. But unfortunately this isn’t always the case…

Bumps on the Trail

While the end result is clean, modular views, getting there can sometimes be a struggle. Simple things, like setting padding around a view can have one scratching your head until you realize that the order of applying View Modifiers matters. When you add them to a view, you’re not simply setting properties on an object as in UIKit, but as the name implies, you’re actually modifying the views. Luckily, despite SwiftUI being a newer framework, most issues like this are in fact Google-able, such as why a row with a Spacer element isn’t registering tap events as you’d expect.

The real struggle occurs when SwiftUI just doesn’t want to do that which you declare. We faced one such frustrating issue trying to allow users to switch their keyboard type while typing. In UIKit, this was as simple as adding toolbar buttons to the keyboard and setting the keyboard type on the UITextField. SwiftUI however handles a similar setup differently. Instead of changing the keyboard type while the keyboard remains on the screen, SwiftUI sees fit to dismiss the keyboard once changes to the type are made, requiring another invocation of editing mode for the new type to appear. This wouldn’t be too big of a deal as we can programmatically invoke the keyboard again with @FocusState — except this does not work in our case where a textfield is within a toolbar and you’re not at the top level of a NavigationStack.

In situations like this it can be very hard to determine if the problem is you, or a limitation of SwiftUI. Others were reporting similar issues here, and we ended up taking the advice posted on Stack Overflow and the Apple Developer Forums… Use the imperative UITextField wrapped in a UIViewRepresentable to achieve what we had before. With our philosophy of “everything new in SwiftUI”, this seemed like a step backwards. We want to set our app up for the future. Adding new UIKit components seemed like taking on technical debt, but in the current state of SwiftUI you do need to make some compromises – either on functionality or technical decisions.

Another challenge is performance. In the world of imperative programming, you can see where views are created and laid out, catching bottlenecks that may slow your app. Such details are abstracted away in declarative frameworks. This can lead to pitfalls where an update to a single textField can cause a cascading redraw of all views if you’re using a single view model for an entire screen as opposed to distinct components each with their own view model. In other cases, SwiftUI views don’t always do quite what you’d think they should. One could reasonably expect a SwiftUI List to act as a performant UITableView would, caching views and updating their content instead of constantly creating new views when scrolling. This however does not seem to be the case. When we used a List to display a large amount of search suggestions, we saw laggy non-performant scrolling. For performant scrollable lists, Apple recommends using a LazyVStack inside of a Scrollview instead. This did work well for us, but it does not seem very intuitive and was not the first thought for fixing our issues.

Looking Back

Our journey transitioning to SwiftUI was both rewarding and challenging. Over 70% of our Ascent’s views are now in SwiftUI. With a couple more releases we’ll get close to 100%. As components are built and knowledge in the framework is gained, the path ahead gets smoother—- both in developing new features and in maintaining and changing existing ones.

Despite the challenges along the way, the journey has been a success. This is in no small part due to the support of the entire team. Our product owner saw the value in adopting the new technology and supported the journey even though it meant less accurate estimates and an occasional change to better accommodate what’s possible in SwiftUI. Our designer composed new features with a set of building blocks, lending themselves extremely well to modular, reusable SwiftUI views. Our testers put the app through the wringer, finding easily overlooked issues and updating UI tests to work with the new layouts. Our project manager kept us focused and moving in the right direction while our backend engineer ensured we didn’t have to struggle to get the data we need. And our architect gave us the nudge to go blaze this trail, giving backup when things got challenging.

Looking back, we are now left with the concise, maintainable view code we were looking for. We’ve also gained vaulable experience in SwiftUI and declarative frameworks that will servce us well in the future. With Android and other platforms also adopting declarative frameworks, the specifics of each platform are becoming less and less important. Perhaps some day in the near future we won’t have to worry about platform dependant view code at all– we’ll be able to simply declare how we want the app to look across platforms.

So, can you trust SwiftUI to pack your backpack? Yes, but make sure to double check the result and be willing to provide some imperative steps if the batteries on your flashlight need changing.

Automated Accessibility Testing: From Passive to Preventative

2023-10-11T00:00:00+00:00

Implementing and scaling automated accessibility testing on REI.com

At REI, we believe that time outside is a fundamental right that all should be able to enjoy. This commitment to inclusion doesn’t start and end with marketing. It’s something we try and live up to every day as we design and engineer new customer features and experiences on REI.com.

Back in 2021, like many other companies, we were stuck in an endless cycle of audit & remediate with our digital accessibility efforts — reacting after-the-fact to the barriers we were putting in front of our customers. Recognizing a need to act sooner, we set out to engineer an automated solution that would be:

Effective — limited in its false positives.
Scalable — easily translatable to any microsite environment within our common framework.
Passive — require minimal human intervention to sustain.
Blocking — not only advising on accessibility issues but preventing them from impacting people in the first place.

Now two years later, we’ve successfully built and scaled a suite of automated tests that are consumed by over 90% of our customer-facing applications, testing thousands of deployments per year for common accessibility missteps, and blocking inaccessible code from seeing the light of day.

We know automation is only 30% of the accessibility testing puzzle, because not everything can be automated today, but we’re proud of the foundation we’ve built and the lessons we’ve learned along the way.

Figure 1: Accessibility Test Count - April '22 to Today

The graph above shows the benefits of integrating accessibility tests into a common framework, instead of relying on a team-by-team approach — rapid adoption. In October 2022, we were running less than 20 tests per day. Today, we're consistently over 300 with a greater than 80% pass rate.

Building for Scale

From the beginning, our most important goal was enabling scalability. In talking to individual employees, we learned that accessibility testing often feels intrusive and additive to the day-to-day work of product teams. We wanted a solution that could be a seamless part of the product development process. Our test suite works by minimizing friction and maximizing positive outcomes for both employees and our customers.

Another reason that scalability was important is due to the rate of change happening on REI.com. With the decomposition of our code monolith into individual microsites and services underway, and due to the nature of our continuous delivery model, new applications are popping up all the time. It’s hard for our small accessibility team to keep up with the maintenance work.

Luckily, many of the customer-facing web applications are built on our in-house framework, Crampon. A common framework allows us to take advantage of pre-existing templating, baking in accessibility best practices and testing infrastructure from day one. It also means that as we started our automated testing journey in 2021, our existing web applications were backwards compatible with our new ideas.

To put in perspective just how easy it is now for developers to implement basic accessibility testing in their application today, I’ve included the steps below for a new or existing Crampon application:

For new applications:

A new application is created via Chairlift, our internal application provisioning service.
The developer gives the application a name and selects Crampon Application to create a Crampon-based microsite or microservice.
The developer chooses Includes microsite UI
After completing the remaining steps in the set-up wizard, the developer now has a repository with our starter application that includes the latest version of Crampon, which includes an accessibility testing starter template by default.
All that’s left to do is specify the URLs to test and implement the isCoOpA11yCompliant method into their existing Selenium-based system tests. These can be written to support tests for basic static content or more advanced applications can include dynamic page states and conditions.

For existing applications:

A new change to the test suite has been introduced in the Crampon repository.
A new version of Crampon has been released.
Existing microsites upgrade their applications to the newest version of Crampon.
All that is left to do is specify the URLs to test and implement the isCoOpA11yCompliant method into their existing Selenium-based system tests. These can be written to support tests for basic static content or more advanced applications can include dynamic page states and conditions.

As you can see, we have taken much of the work of understanding accessibility and test libraries out of the equation and let test engineers do what they do best, write tests.

Ensuring effectiveness

With scale comes challenges related to the effectiveness of our test suite. A one-size-fits-all solution isn’t tremendously effective, especially with 22 unique applications serving customer functions from landing page to checkout. Not to mention how diverse our product teams are in their approaches to writing acceptance criteria, code, and tests.

Our first step was to decide on a base test library that could limit false positives while remaining flexible enough to conform to each unique application in a way that was seamless and performant. After extensive testing, we landed on axe-core. It’s free, open source, something we were familiar with already, and allowed us to add/remove rules and standards easily.

Then, after careful consideration, we narrowed down our current ruleset to just 42 rules. We intentionally exclude page elements that are included as part of our base template to eliminate test noise and ensure our suite is performant.

With a solid ruleset in place, our next move was to exclude the header and footer navigation for testing and only test content within the core page content for each application. Our navigation is persistent across many pages, and we found that choosing to test this code once in isolation, compared to testing it within every application removed a lot of noise caused by test failures, allowing teams to work quicker.

Accessibility tests run against our navigation (header and footer), as well. Our Header/Footer exists as its own microsite, which makes testing it easier.

Finally, we needed to make it easy to make our tests blocking for deployments. We want to prevent issues from impacting customers. To do that in a way that’s durable, we needed to ensure tests are always passing, by accounting for the code we don’t own — 3rd party vendor content. Without doing this, 3rd parties could release inaccessible code and prevent our developers from pushing to production.

We solved this problem by developing and implementing a change to our test suite via Crampon that enabled developers to skip testing for certain selectors within their UI.

We rolled this out globally by working with individual teams to upgrade to the most recent version of our common framework. And with our implementation in place, teams are easily and efficiently able to understand how well their application does at passing automated accessibility tests, without the noise that navigation and vendor solutions might add.

Ushering in preventative measures

With accessibility tests running on every microsite and in many cases passing, we could have stopped there. However, we were determined to do more than tell people their code had accessibility issues.

We wanted to prevent the negative impacts of inaccessible code before it became reality.

Initially our test suite was running in production only. In theory, we could have flipped the Boolean value from false to true and prevented people from shipping code that didn’t pass the test. This would have been a bit heavy-handed and potentially added additional friction when folks were on a tight deadline or in a code-freeze situation.

Instead, we chose to implement an identical set of tests in each team’s staging environment. This acts as a proxy for blocking tests with less risk to deployments since teams test their work in staging before pushing to production. So far, this has been effective in preventing regression without negatively impacting our teams’ workflows.

Road to maturity

Now you’re wondering, how did you scale so quickly? and much of that success can be attributed to our maturity plan, illustrated in the graphic below by our Principal Accessibility Engineer, Harmony Hames.

Note: For the purpose of this article you can think of staging environment and try pipelines interchangeably. This is pre-production code.

Figure 2 - Illustrating how REI.com applications implemented our test suite

Getting teams to prioritize accessibility testing wasn’t easy, and it wasn’t an overnight success. The choices we made and the features (like exclude functionality) we developed were the result of a lot of trial and error. It took us almost 2 years to get to the stage we’re at now. That said, we chose to ease teams into change vs. forcing a lot at once as illustrated above:

Upgrade to the latest version of our framework, Crampon
Ensure you’re using the latest test method.
Get your production tests configured correctly if they’re not.
Get your production tests passing.
Implement tests in your staging environment to prevent regression.

At any given time, you’d have 2 teams in stage one, another few with passing tests, and a handful of others not on the latest version of Crampon. It felt like chaos but having a well-documented plan for a team to mature their practice and only 1-2 things to focus on at a time, provided just the right amount of motivation for teams to achieve what looked impossible.

Finding and closing the gaps

The tests are running on most user experiences, passing, and they’re blocking. We’re done, right? Not quite.

Though the reality of the situation was that we’re running over 400 tests, split between staging and production, and most of REI.com is templated, we found that they were only as good as the templates we were covering. There were page types we weren’t covering with any accessibility tests.

To solve this problem, we needed to understand where the gaps were, and then improve each application’s tests to achieve optimal coverage. To do that, we needed to drastically expand the scope of the tests, since today our problems were outside of our existing URL set.

One, albeit cumbersome, way to determine which page types weren’t being covered, would be to browse them like a user would and run a browser extension (in our case axe DevTools, since it’s an identical test library to our pipeline tests). If there were test failures, it meant it contained failures due to rules we’d skipped, or it wasn’t tested.

Based on a set of 2,600 pages which we believed would cover all page types, we estimated this route would take an estimated 86.6 hours to complete (2 min x 2,600 pages / 60 min). This is way too long, and way too cost prohibitive, especially if we wanted a solution that would keep up with our site’s pace of change.

Arborist

Enter Arborist, our homegrown automated solution to doing the work described above. This key piece of technology unlocked several benefits for us as we reached for the best possible test coverage:

Increased visibility (9000% larger scope)

3rd party audits of REI.com are especially limited in scope due to cost.
Our pipelines are testing an estimated 400 pages.
Arborist tests around 2,600 pages.

Increased efficiency (-94% reduction in time to results)

A human triggering the automated tests via a browser extension (axe DevTools, Google Lighthouse, etc.) would have taken an estimated 86.6 hours (2 min x 2,600 / 60 min) to complete a run of 2,600 pages.
Arborist runs for an average of only 4 hours and 32 minutes.

Increased frequency

A human might test pages only as time and bandwidth allows.
Arborist runs on REI.com every Friday.

Increased flexibility

Test libraries, people, and standards change. With an extra tool that runs outside of our deployment pipelines, we can now test new enhancements and rule sets before impacting product teams with global changes.

Since we’ve launched Arborist, we’ve been able to dial in our test coverage and improve upon the work we’d already worked with teams and applications to adopt. Additionally, we’re able to get more data, more often, something that’s been a challenge in the accessibility space.

Figure 3 Each run of Arborist has shown a notable decline in automated accessibility issues, indicating we're not regressing, and highlighting what's remaining due to 3rd party vendors.

Conclusion

Though we still have a lot of work to do, knowing that automated accessibility testing can only really prevent 30-50% of issues, and that manual testing is required, too, we’re proud of the testing infrastructure we’ve built. We hope to close the remaining gaps with the manual testing standards we’re piloting now.

What was once a culture of annual audits and remediation, is now one that regularly checks in on whether their accessibility tests are passing. We’re actively preventing accessibility issues from reaching customers, leading to a more accessible and friendly shopping experience.

Putting people over profit, so all people can enjoy time outside.

Introduction to Chaos Engineering

2023-06-14T00:00:00+00:00

Does the thought of being oncall for a critical service keep you up at night? (Or do bears?)

Customer scenario

Let’s say you had a great day walking around the zoo. Say hello to Huckleberry. Or is it Hawthorne? Does it matter? Look at those claws!

The thought of meeting either one in the wild keeps you up all night, so you decide to do some shopping.

Clicking submit order and ready to go back to bed. Wait a minute - didn’t go as planned?

Engineer scenario

You’re the oncall engineer supporting REI’s shopping cart & checkout and you get an alert in the middle of the night that some service (xxxService) is throwing errors. After dialing into the major incident conference call you are asked what is the customer experience when xxxService is unavailable? Panic time, right? Good thing the camera is off!

REI’s Checkout microservice orchestrates numerous dependencies to provide shopping cart and checkout functions for rei.com and mobile apps. For example, Customer Info, Dividend, Gift Card, Credit Card, Coupons, etc. With so many dependent services, it’s inevitable that something will break at some point. The goal is to minimize the customer impact during checkout.

Purposefully fuzzy relationship image

Chaos Engineering to the rescue?

Chaos testing is just one of the many types of testing we do at REI to ensure our services are working properly.

From Principles of Chaos Engineering:

Chaos Engineering is the discipline of experimenting on a system in order to build confidence in the system’s capability to withstand turbulent conditions in production.

There are many types of tests that you can do that could fall under the umbrella of Chaos Engineering. For the purposes of this article, I have focused on testing individual services going down.

Game day scenario

This works best with the whole team present: Developers (frontend & backend), architects, SDETs, product managers, etc.

Hypothesis - What happens when the xxxService is unavailable?
Test - Disable xxxService. Since all of our services are invoked using the Resilience4j circuit breaker, this is achieved by putting the breaker into “Open” state. We did this in our test environment. You could also change the read timeout to 1ms, or use Wiremock or something similar to respond with a 5xx error. Side note - we’ve migrated from Hystrix to Resilience4j. See excellent article from Jeremiah Pierucci here.
Observe - Did it behave the way you expected? While going through the exercise, sometimes the hypothesis did not match what we observed, and we needed to make some change to address it. In other cases, the website did not behave the way we wanted it to. Doing this live with the whole team was very enlightening for me, as we sometimes had different ideas of how the site should behave (For example, what happens when xxxService is not available - should it block customers from submitting their order? What should the user experience be?)
Fallback - do we want to add a fallback response when any of the services are down?
Document - With so many dependencies it is important to document the expected behavior (otherwise I won’t remember at 2 am when I am oncall)

Continuing the Chaos journey

This testing is not intended to be done one time only - you will need to be diligent when new services are added, and it would make sense to repeat these tests on a semi-regular basis, as other parts of the code could have changed.

The experiment described above can be thought of as a building block of Chaos Engineering. As you gain confidence in this testing, you could increase scope to include things like database, cloud infrastructure, spikes in traffic, or really anything you can think of that could disrupt your service. Eventually, as your Chaos Engineering practice matures, you could automate these tests and add them to your build pipeline, and perhaps eventually test in production.

Hopefully, the result is that both customers and oncall engineers sleep well at night. You do have robust monitoring and alerting for your application, right?

Accessibility + content design: a powerful combo to make you a better developer

2023-03-06T00:00:00+00:00

A silly story that helps illustrate the benefits of understanding both accessibility and content design.

Introduction

If you didn’t learn about accessibility when you were learning development, you’re not alone. Even today it’s rare to find a development course offering more than a passing mention.

Writing accessible code, at its core, means writing code correctly. When combined with accessible content design, it will make your site generally more usable.

But more importantly, it enables people with disabilities to experience, and use the internet. In the world we live in today, that is unquestionably a human right.

Learning accessibility is no small task. There is much to learn, but it can be broken up into phases. Many certification courses will provide study outlines, or you can create your own. No matter how you choose to learn, it is well worth the effort.

Here are just a few of the basics:

You’ll learn about WCAG (Web Content Accessibility Guidelines), which will give you:

A framework to help you understand the basic concepts of accessible web content.
Success Criteria that provide techniques and a framework for testing your work.
A deeper understanding of how an inaccessible web impacts people with disabilities.

You’ll learn about ARIA (Accessible Rich Internet Applications), which has:

A library of existing patterns for web components in the ARIA Authoring Practices Guide (APG).
The expected keyboard patterns for these components.
Best practices around designing keyboard patterns for novel components.
Roles, states, and properties of elements on the web.

You will dive deeper into semantic HTML, and understand why it is critical for those using assistive technologies.

Some examples of how this knowledge will benefit you as a developer:

Your perspective will be more inclusive. Not all users use a mouse. Not all users can see the screen. You’ll move away from this “default thinking.”
Your code will be more performant. Semantic and well-structured code requires less scripting and fewer DOM nodes.
Your code will be SEO-friendly. Using semantic elements and avoiding duplication of content is good for SEO rankings.
You’re less likely to create device-specific bugs. Alternative input methods will be top-of-mind. Using built-in browser functionality is more reliable than custom coding.
You will be more confident. You’ll learn to quickly break down designs into known components and patterns.
You will be more efficient. You’ll see design issues in refinement, instead of bending over backward to fix them in code.
You will be more employable. This case study notes that “A study reported that web designers with competence in solving accessibility problems are more employable.”

How content design thinking and accessibility work together

Content design is about determining the best way to present the info people need to get stuff done—before getting into detailed interface design. Once the content and story interactions are clear, the design should center around that story flow and reinforce it.

Developers can play a role in this by helping to preserve the meaning of content when they see it getting lost in design translation. It can be a strong habit to look at a visual design and immediately start converting it into a layout. But by seeing a design first as a content outline, it becomes easier to recognize potential issues.

Many of the skills you gain learning accessibility support this kind of thinking. We’ll use an example to demonstrate this in action.

Starting with a visual design, we’ll examine how the average developer might start to break this down conceptually.

A story of space creatures

For this mental exercise, we’ll put together a fake team:

Ted: The designer. He’s new on the job, but he’s doing his best.
Chadwick: a traditionally trained front-end developer.
Allie: a front-end developer who trained in accessibility best practices.

We’ll pretend this design contains actual content and not Forcem Ipsum.

This is how the design came in from Ted.

Shown above: The mobile version of the layout, showing the content in understandable reading order. The full text of the layout is below, but it is not necessary to read it to understand this article (maybe just to get a laugh).

Show full image text

Note: the heading levels are given here based on appearance (size).

Image of a child (will be described below, no spoilers!)

Heading level 1: Ewoks and ET: A Risky Mix

The approach will not be easy. You are required to maneuver straight down this trench and skim the surface to this point.

The shaft leads directly to the reactor system. A precise hit will start a chain reaction which should destroy the station. Only a precise hit will set up a chain reaction. The shaft is ray-shielded, so you’ll have to use proton torpedoes.

May the Force be with you!

Heading level 2: Speeder bikes AND flying bicycles?

At least the information in Artoo is still intact. What's so important? What's he carrying? The technical readouts of that battle station. I only hope that when the data is analyzed, a weakness can be found. It's not over yet! It is for me, sister!

She lied! She lied to us! I told you she would never consciously betray the Rebellion. Terminate her...immediately! Stand by, Chewie, here we go. Cut in the sublight engines. What the...? Aw, we've come out of hyperspace into a meteor shower.

Heading level 3: Speeder bike technology

You're sure the homing beacon is secure aboard their ship? I'm taking an awful risk, Vader. This had better work. Not a bad bit of rescuing, huh? You know, sometimes I even amaze myself. That doesn't sound too hard. Besides, they let us go. It's the only explanation for the ease of our escape. Easy...you call that easy? Their tracking us! Not this ship, sister.

Image of a wookie (again, description below, no spoilers).

Heading level 2: What about Wookiees?

They'll have that shield down on time.

Earned it, I have. Master Yoda, you can't die. Strong am I with the Force. but not that strong! Twilight is upon me and soon night must fall.

He will come to you and then you will bring him before me. As you wish. Luke! Luke! Oh, Master Luke. I'm afraid that Artoo's sensors can find no trace of Princess Leia.

Wait, Leia! Quick! Jam their comlink. Center switch! Hey, wait! Ahhh! Move closer! Get alongside that one! Get him! Keep on that one! I'll take these two!

Shown above: The desktop version of the layout.

In this version, the content appears to be in two columns, and the order has changed. Now "What about Wookiees?" comes right after the opening section, and the image of the Wookie has moved to the end of the content.

When the team meets to review the design before development, Ted asks if there is anything that needs clarification.

Chadwick’s review

Chadwick thinks about the visual design and how it compares between desktop and mobile. He looks at which elements shift, and thinks about how to do this with CSS. He notes a few things:

It’s clearly a column design on desktop.
The elements are in a different order between desktop and mobile. He thinks through ways to handle that:
- CSS Grid? Maybe. He could rearrange the content with grid-template-areas. But with the column design, he would likely have gaps as the page resized. Any answer to that is likely to be quite fussy, but possible.
- He could duplicate the content and use CSS to show/hide the areas at different breakpoints.
- He could use a buffered resize listener to move the content on page resize.
Other than that, it’s just basic elements - heading, text, and images.

Chadwick asks Ted asks a few questions about how the page layout changes at different breakpoints. Other than that, he thinks he’s got it.

Allie’s review

Allie takes a content-first, accessibility-focused approach. For this design, she considers:

Semantic HTML and reading order.
The way assistive technology will interact with the page.
Other ways that users might experience the page, or change the display.

This brings a few things to light:

There is non-text content (images) that will need alternative text for those who can’t see the screen.
The banner under the “What about Wookiees” heading only exists on desktop.
The design dictates a change in reading order.

She addresses these issues one at a time.

(#1) Missing alternative text

She asks about #1 (alternative text for the images) first. Ted quickly scratches out some alternative text, and their project manager adds it to the ticket:

Image 1: “An eight-year-old child with a bowl haircut, wearing pink corduroy pants and a baseball shirt with blue arms and E.T. on the front. She stands holding a cardboard cutout of an Ewok, in front of a Star Wars backdrop.”
Image 2: “A line sketch of a Wookiee, by an artist who is clearly quite skilled.”

(#2) Content exists on the desktop layout that is missing on mobile

Allie asks Ted about the “Did you know…” banner that is added on desktop. Ted decided to add this to give the page a bit more visual flair and help with the layout balance.

Allie frowns. “So if someone uses a screen magnifier, they may trigger the mobile version of the page. That content will essentially never be available for that person. That’s also a violation of WCAG Success Criteria 1.4.4: Resize Text (Level AA). Is that content important?”

(#3) Changes in reading order

She does a mental outline of the hierarchy and changes in the reading order.

For now, she leaves out sectioning elements, like <article> or <section>. However, she notes that they would be difficult to use properly on the desktop version.

Mobile:

img: Ewoks and et picture
h1: Ewoks and E.T.: A Risky Mix
- p: related content
- h2: Speeder bikes AND flying bicycles?
  - p: related content
  - h3: Speeder bike technology
    - p: related content
- img: Wookiee picture
- h2: But what about Wookiees
  - p: Wookiee-related content

Desktop:

h1: Ewoks and E.T.: A Risky Mix
- p: related content
img: Ewoks and E.T. picture
- h2: But what about Wookiees
  - p: Did you know? ...
  - p: related content
- h2: Speeder bikes AND flying bicycles?
  - p: related content
  - h3: Speeder bike technology
    - p: related content
- img: Wookiee picture

Looking at the content this way, she notes that the order of the content changes significantly on desktop.

One of these changes is fine. The picture related to the “Ewoks and E.T.” content still stays tangential to the content. Whether before or after doesn’t affect meaning or understanding.

However, the sections change reading order, and the Wookiee picture ends up no longer being in a section with its related text.

Allie asks Ted about this. He explains that he wanted the Speeder bikes section to be above the fold. The column design was mostly used to help the image layout.

“Unfortunately,” Allie says, “This will create a reading order that changes meaning on desktop. Not only for screen reader users—but also for desktop users that follow the vertical column flow to read. They will have a disjointed reading experience, where content is read out of order. This is a violation of WCAG Success Criteria 1.3.2: Meaningful Sequence (Level A).”

The pushback

Chadwick is looking a little annoyed at this point. “Allie,” he says, “it’s not our job to question the design, we just implement it.”

Allie shakes her head. “Sorry Chadwick, but it is our job to question a design if we can’t implement it in an accessible way. Not to mention, if the content retains the same order on desktop, there will be other benefits. Namely: performance, SEO, and code maintainability.”

“For example, duplicating content means extra DOM nodes, which is bad for performance and code maintenance. When that content includes heading tags, it can also be bad for SEO.”

Chadwick interjects: “Ok, fine, then we’ll use Javascript to move the content with a resize listener.”

Allie replies, “That covers SEO, but is still affecting reading order, performance, and code maintenance.”

“CSS grid? Rearranging the content in template areas?”

Allie sighs. “Even if you could get that to work, you still would have an issue with the reading order. And any changes in the content would mean reworking the grid.”

At this point, Ted jumps in. “No worries team. I had some of these thoughts myself when working on the design. I’ll take this one back to the drawing board for now, and we can look at it again in the next refinement session.”

The redesign

Two weeks pass, and Ted has come back with a new design. He’s thrilled to present it.

Shown above: The fixed desktop version of the layout.

In this version, the content is in the same general order as the mobile design. There are two rows this time. The first one has the image of the child on the left, and the paragraphs about "Ewoks and ET" and "Speeder bikes" on the right. The next row is centered with a border and contains the Wookiee-related text on the left, with the Wookiee drawing on the right.

“In this new design, I can show the full picture of this fashionable child, including these astounding pink pants. This design should also work better at tablet size than the last one did.”

Allie looks it over, doing a quick mental outline. Now all the content is in the same order/hierarchy, except for the Wookiee picture. But the picture is still tangential to the related content, so that’s fine. She gives a nod of approval. “It looks like you decided to get rid of that extra banner in the Wookiee section?”

“Yeah,” Ted smiles sheepishly, “that never really fit with the purpose of the content. It was just filler - so I took it out.”

Now both developers are happy with the design. Furthermore, Ted has learned to think in a more content-first manner, so his next design will take that into account.

Was it a little awkward at first? Sure. But in the end, these tough conversations result in an improved experience for everyone.

The new design has improved in many ways:

It’s more performant and SEO-friendly.
The page has a more natural and readable flow for all users.
The code will be more maintainable, as it won’t need any hacks to work around an inaccessible design.
The developer won’t have to interrupt the designer after they’ve moved on to the next project (for example, to ask for alternative text).
And of course, the page will be accessible: delivering an equal experience for users with disabilities.

The bottom line is, you can’t take any design and make it accessible. If the design itself is not accessible, it is your place to speak up as a developer.

Both design and development are more likely to be accessible if they center around the content. If we can all align in that thinking, we can help each other improve.

Resources

Accessibility basics

Web Accessibility Initiative (WAI) | W3C: A central hub for learning about accessibility fundamentals. Many of the resources provided below are within this space.
Accessibility, Usability, and Inclusion | WAI | W3C: Understand how accessibility, usability, and inclusive design overlap, and their unique concerns.
WCAG 2.1 Understanding Docs | WAI | W3C: A deep dive into each of WCAG’s Success Criteria, explaining the intent of the rule, who it benefits, examples, and suggested techniques to meet that criterion.
WCAG (Web Content Accessibility Guidelines) | WAI | W3C: The official specification, for when you’re ready for all the details.

ARIA - Accessible Rich Internet Applications

Using ARIA | WAI | W3C: 5 really important rules to know before using ARIA, plus other tips and best practices.
ARIA Authoring Practices Guide (APG) | WAI | W3C: Component design patterns and examples, best practices, and much more.
Accessible Rich Internet Applications (WAI-ARIA) 1.1 | WAI | W3C: The official ARIA spec. This is a lot to dive into without some basic background first, I suggest starting with the links above.

Semantic HTML

HTML: A good basis for accessibility | MDN web docs: The basics of semantic HTML and the benefits it offers.
Accessibility Through Semantic HTML | Laura Kalbag, 24 Ways: A great summary of the benefits of semantic HTML, and how to test your work.

Content Design

What is content design? | Content Design London: A great intro for understanding content design and how it answers users’ needs.
Writing is Designing | Michael J. Metts and Andy Welfle (book): How to approach writing for the web as a form of design.
The Massive List of Content Design & UX Writing Resources | Prose Kiln: A list of books, articles, websites, courses, and much more.

Tutorials and resources for beginners

Digital Accessibility Foundations Free Online Course | W3C WAI: An intro accessibility course for developers, designers, content authors, and anyone else who wants to learn the basics.
Learn Accessibility | web.dev: A great overview of the basics, and a good reference.
Testing Accessibility Courses (paid course) | Marcy Sutton: A well-known accessibility advocate, Marcy offers three levels of courses with a hands-on, simplified approach to testing the accessibility of your web pages.
Introduction to Screen Readers (video) | YouTube, Tim Harshbarger (A11yTalks - February 2021): Tim teaches about screen reader basics and how testing with screen readers is different from the way they’re actually used.

Tools and reference

There are far too many tools to list all the good ones. This list is slimmed down to some of those tools I use on a regular basis. Start with a few and see how they work for you.

How to Meet WCAG (Quick Reference) | WAI | W3C: A filterable quick reference list of all the WCAG criteria. A great way to find criteria by role, level, or subject (for example, “audio”).
Accessibility Support (allysupport.io): Check elements, attributes, and more to find details on feature support. While not always 100% up to date, it’s still one of the best tools for this task.
Accessibility Insights: A testing tool created by Microsoft, available for Web (Chrome and Edge), Android, and Windows. It offers the ability to scan your page for issues using the axe-core library, as well as tools that support manual testing.
Screen Reader Keyboard Shortcuts and Gestures | Deque University: Great shortcut guides for lots of different screen readers, in web or pdf versions.
Color Contrast Checker | TPGi: An installed application for Windows or macOS, it can test color contrast on live sites or design mock-ups with a simple eyedropper tool.

References

Accessibility in Web Development Courses: A Case Study | MDPI

The front-end build tool renaissance at REI

2023-02-02T00:00:00+00:00

The Front-end Build System (FEBS) is REI’s internally developed set of tools that helps engineers build the assets that are eventually downloaded by customers visiting REI’s online properties. FEBS has evolved over the years to support an ever-changing development landscape.

The first generation of FEBS was built directly in our legacy monolithic code base, a series of scripts that leveraged some programmable APIs from libraries like gulp and browserify. This code continues to serve any remaining applications living in that monolithic space.

The Co-op moved toward a more decentralized approach by introducing microservice architecture with the development of the Alpine platform. With this came a new generational iteration of FEBS that was decoupled from any individual implementation. FEBS 2 lives in REI’s internal NPM registry as @rei/febs with several other supporting packages. It is declared as a dependency of an Alpine microsite.

Under the hood, @rei/febs is extending webpack@4 to bundle web application code and rollup@2 to bundle Vue 2 components and vanilla JavaScript libraries.

Unforeseen consequences

Our team maintains a microsite that contains supported patterns, technologies, and most importantly, an end-to-end functional example used as a reference by other product teams. We expected @rei/febs to canonicalize the way teams built their front-end assets and thereby reduce any individual deviation from supported patterns, theoretically improving the interoperability ecosystem.

For most cases, @rei/febs did its job. However, as time went on, feature requests continued to pour in to accommodate product teams with unique business requirements. Additionally, the underlying dependencies supporting @rei/febs continued to change, forcing us to manually reconcile them within our packages and within individual microsites.

The maintenance of iterating on @rei/febs and troubleshooting microsite build issues began to consume our daily lives. Worse was that @rei/febs was becoming bloated with logic for many unforeseen use cases.

Inherit apparent

Perhaps you spotted the inherent problem with @rei/febs? It’s an inheritance model. @rei/febs extends several build tool technologies including webpack and rollup. This means that @rei/febs is webpack. @rei/febs is rollup. So, what’s the issue? Inheritance models are brittle by nature (don’t @ me). Any change request can require a massive overhaul of the implementation. And the more you customize, the harder it becomes to maintain until it becomes an unrecognizable, enormous blob like in Akira.

This is the way

Eventually, we hit a wall when Vue 3 arrived on the scene. We built a POC that brought Vue 3 support to @rei/febs. We discovered that the Rollup plugin used to compile Vue 3 SFCs for our public design system, Cedar, made tree-shaking incompatible with webpack@4, resulting in bloated application bundles.

Even though we had a functional POC of our reference microsite using Vue 3, we were unsatisfied with the low-level work we had to do to get there. We decided to experiment with a build toolchain overhaul that dispensed with our implementations in favor of using Vite to bundle our application. We quickly cobbled together a working solution. We liked the approach so much that we decided to move forward with it.

Enter Vite

Vite is a UI-framework agnostic build tool. It supports React, Svelte, Vue, and others. It’s a bundler … of bundlers. Ironically, it’s a wrapper that swaps bundlers in and out for different purposes. But the key point here is that it’s a wrapper maintained by an open-source community instead of us. Under the hood, it uses rollup and esbuild.

Vite happens to have first-class support for Vue, which makes sense, as it was built by the creator of Vue. REI is a Vue shop. Our design system, Cedar, is a Vue component library. Cedar now uses Vite to bundle its code. We’ll use Vite to bundle our customer-facing Vue 3 applications. One tool to rule them all.

Besides all that, Vite is pretty sweet. It has a “no-bundler” approach to running its development server. It doesn’t need to build your application before it’s served.

Vite serves source code over native ESM. This is essentially letting the browser take over part of the job of a bundler: Vite only needs to transform and serve source code on demand, as the browser requests it. Code behind conditional dynamic imports is only processed if actually used on the current screen.

So, what is FEBS now?

FEBS 3 is the “Front-end Build System”, but that system isn’t an explicit dependency.

Rather, it’s a curated collection of open-source tools that are declared as dependencies of Alpine microsites and NPM packages used to bundle assets. Specifically Vite and Vitest. These tools are supplemented by REI-built configurations, plugins, and patterns to support REI-specific needs.

This has alleviated us from low-level dependency management, makes future migrations and tool swaps easier, and allows engineers maximum flexibility with their application builds while always having a functional example to reference. Engineers can also lean directly on the open-source community for any issues they may have with a particular build tool.

Lessons learned

Reflecting on the evolution of the build toolchain at REI, the intentions were good. Create a tool that would normalize the way our teams built front-end assets and prevent deviation from supported patterns.

What we learned was that we didn’t need to be restrictive in the form of an explicit tool like @rei/febs. It’s not like people couldn’t get around it anyway. Instead, we simply provide sanctioned patterns and people use them. The benefits of using the raw build tool greatly outweigh a customization that extends the tool directly.

REI Co-op Engineering

Server Driven UI: Prepared for the Unknown

You won’t know ‘till you get there

How do you plan for the unknown?

Implementing SDUI in the Price Change Tool

Querydsl

Example Implementation: Query Parameters -> SQL

Sample URL

Converting Filter Values to a JPA query

The Resulting SQL Query

Exposing Query Options with SDUI

So did it work?

Impact to our users

Impact to our team

Bonus Section: Explicitly Typed Queries in Querydsl

QueryDslExpression

QueryDslQueryableEntity

Store Technology: Building Alongside your Users

On the path to “Product-Led”

Why is it so hard to know what the user wants?

Problem #1: The user is in a galaxy far, far away

Problem #2: Competition

What if we didn’t have to worry about either of those issues?

Ascent: built with employees, for employees

The Problem

Research Pt. 1: The Listening Tour

Research Pt. 2: Frequent Check-Ins with Users

Bonus: Standard Operating Procedures

The Solution Pt. 1: Pilot Releases

The Solution Pt. 2: Rapid Iteration

The Good Part

XCUITest Automation: Page Components for iOS Test Automation

Creating Stable, Maintainable User Interface Test Automation in Swift

Functional grouping with page components

ProductDetailsView excerpt

ProductTitleBlock

Page component with unique search context

Defining search context for singleton page component

Search context for page component collection entries

Defining unique search contexts for page component collection entries

Summary

XCUITest Automation: Page Object Models for iOS Test Automation

Creating Stable, Maintainable User Interface Test Automation in Swift

Implementing Page Object Model (POM) patterns in Swift

Synchronization - The lynchpin of stable automation

The SynchronizedView protocol

Page Object Model Protocol (Part 1 - Synchronization)

Navigation - Building a chain of synchronized views

Page Object Model Protocol (Part 2 - Object Chaining)

Best practices for stable automation models

Best practices for test implementation

Handling transitions with interstitial “toast”

ToastInfo

TransitionWithToast

Summary

XCUITest Automation: Encapsulating Element Locators in Swift Enumerations

Creating Stable, Maintainable User Interface Test Automation in Swift

Defining element locators in Swift enumerations

Summary

Note regarding another enum-based locator definition strategy

Switching Trails to SwiftUI: Our Journey at REI

Declarative vs. Imperative Programming

Deciding to Declare

Navigating the Move to SwiftUI

Bumps on the Trail

Looking Back

Automated Accessibility Testing: From Passive to Preventative

Building for Scale

Ensuring effectiveness

Ushering in preventative measures

Road to maturity

Finding and closing the gaps

Arborist

Conclusion

Introduction to Chaos Engineering

Customer scenario

Engineer scenario

Chaos Engineering to the rescue?

Game day scenario

Continuing the Chaos journey