Introducing Gauge

Introducing Gauge, a framework for User Journey tests.

Presented by Scott Davis. His email address is His Twitter handle is @scottdavis99.


Keyboard Shortcut Description
→ or [space] Next slide
Previous slide
f Fullscreen view (toggles on/off)
t Transcript view (opens in separate window)
p Play/pause audio for the current slide.
a Auto-play audio and advance to next slide. (toggles on/off)

Here are some quick keyboard shortcuts to help you get around.

  • Press the right arrow or space bar to go to the next slide.
  • Press the left arrow to go to the previous slide.
  • Press 'f' to toggle full screen mode.
  • Press 't' to open the written transcripts in a separate window.
  • Press 'p' to play or pause audio for the current slide.
  • Press 'a' to autoplay audio and advance to the next slide.

Scott Davis' Biography

Hi! My name is Scott Davis. I'm currently a Principle Engineer with ThoughtWorks. Before that, I ran a software consultancy out of Denver, Colorado called ThirstyHead.

I've been writing about web development for years -- articles for IBM, books for O'Reilly and the Pragmatic Bookshelf, and most recently videos for O'Reilly as well.

Gauge home page

Today, I'd like to talk to you about Gauge, a free and open source testing framework for acceptance testing.

But before we get too far, I think that it's worthwhile to define some terms more clearly. You'll hear me call acceptance testing "User Journey testing", which I think is a better description of what we're trying to accomplish when we use Gauge. Either way, this kind of testing is significantly different than the kind of testing that you probably do today, if you're a typical front-end developer.

Frameworks and Unit Testing

Most modern web frameworks ship with their own unit testing library. If you're a fan of React, then you're probably intimately familiar with Jest. Angular developers use the baked-in library Jasmine to do their unit testing.

The Test Pyramid

Unit tests are a crucial part of the quality equation. They form the foundation of the Test Pyramid. Since most web developers write their own code, these unit tests allow them to test their own code. They're typically fast to run and easy to write, since they are designed to run in isolation from the other, more complex parts of the application stack (like databases and web services).

I often say that unit tests "test the bricks, not the building". After all, you can't trust the building if you don't trust the bricks.

As you move farther up the Test Pyramid, you move farther away from the source code, and get closer to the actual users of your application. (Keep this in mind when we begin talking about User Journey tests.) You add more pieces to the puzzle, and correspondingly add more places for your tests to fail.

If your organization doesn't have a solid testing or integration environment -- one that mirrors the production environment as closely as possible, and one that is trivial to set up and tear down repeatedly as you run your integration tests -- this is where testing can become less common. Not because the tests are less important, but sadly because they can be harder to run reliably.

Unit Testing

I see a lot of unit tests out in the wild that may or may not truly be "unit" tests in the strictest sense of the word. Since any test is better than no test, I hesitate to criticize tests that might not be as isolated as I'd prefer in an ideal scenario.

But here's one definition of a unit test that I hope that we can all agree on -- unit tests are for the benefit of the developer, not the user. As much as I'd love it, I've never had a user ask me how much code coverage I have for the website I'm demoing, or how many edge cases I've tested for null pointer exceptions. While users certainly benefit indirectly from a solid coverage of unit tests, I'd argue that developers are the most direct, primary beneficiaries of unit tests.

React Unit Testing

Here's an example of what I'm talking about. If you write a custom 'sum' function in React, you've almost certainly got a corresponding unit test to make sure that your custom function accurately does what it promises to do. Notice that this 'sum' function is completely isolated from the web view that the user can see, or even some higher level function of yours that depends on the fact that 1 plus 2 does, in fact, equal 3.

Angular Unit Testing

Here's another, slightly more realistic example in Angular. The developer has created a 'Lightswitch' component, and like all good responsible developers do, they have created a corresponding set of unit tests to test this component in isolation.

From the end user's perspective, they are ticking a 'use default shipping address' widget on screen, or 'bill to credit card on file'. They most definitely benefit from having a well-behaved Lightswitch component, but when you look at the tests, it's pretty clear that they were written for the benefit of the next developer who comes along and stumbles into this part of the codebase, not the end user who will actually be interacting with the Lightswitch directly.

Gauge home page

So, remember Gauge? That was the whole reason we started having this conversation in the first place, right?

Now that we have a better understanding of what unit tests are and who they are written for, let me say this: Gauge DOES NOT replace your current unit testing library of choice. Gauge is for writing user-focused tests, not developer-focused tests. Gauge is for writing User Journey tests.

User Journey Test

User Journey tests are written in the language of the end user, not in the language of the developer (either programming or spoken). Users typically say things like, "I'd like to add tomatoes to my shopping cart", not "I'd like to add the UPC string of the selected item to that array of strings over there in the Cart component."

Now, while literal-minded developers might scoff and think, "Meh, as long as the functionality gets tested, does the language of the test really matter?"

Here's the deal: it does. It really does, especially when we're talking about User Journey tests. You can call them "acceptance" tests, because what we're trying to figure out is what an "acceptable" website looks like to the user -- Is it acceptable if you can't add items to a cart? Is it acceptable if you can't check out and actually purchase the items?

So by calling these tests User Journey tests, it brings the user back into forefront the conversation. The tests are written in the user's language. The acceptance of the finished project is ultimately up to the user, not the developer.

Design Thinking starts with empathy.

If you ask a typical developer what step #1 of a new project is, chances are good that they'll say something like, "Pick a web framework" or "Set up a new code repository".

If you ask a fan of Design Thinking what step #1 of a new project is, they'll say, "Empathy". Putting yourself in the mindset of the user. Understanding what they want to accomplish when they use your app.

Because if you start writing tests in the language of the user, it helps you think like a user. And then, it opens up creativity in an entirely different part of your brain. "Hmmm, if I buy tomatoes every week, wouldn't it be cool if I could just re-purchase last week's shopping cart full of the food I normally buy?" "I'm already uploading a pre-written shopping list to my cart for my automated unit tests -- I wonder if it would make my users lives easier if they could do the same thing?" works GroceryWorks

So, here's a website for a fictional grocery store called GroceryWorks. As you click around, you'll see that tapping the categories on the left show you different types of food items -- beans, nuts, pasta, produce, and so on. Clicking on a food item adds it to the cart on the right. Clicking on the food item again removes it from the cart. Clicking 'Purchase' allows you to place your order or cancel it.

Gauge Specs

User Journey tests in Gauge are comprised of two complementary parts -- Specifications, written in Markdown; and Tests, written in the programming language of your choice. (More on that in just a moment...)

Markdown is basically plain text with some simple decorators like hashes for headers (which represent the name of your specs) and asterisks for bullet items (which represent the individual steps to take). Markdown gives you the flexibility to express the steps in exactly the language your end user uses to describe them.

Gauge Impls

You can implement your tests in a variety of popular programming languages: JavaScript, C#, Java, Python, or Ruby. What you're seeing here are the tests implemented in a JavaScript library written by ThoughtWorks called Taiko. I'm really impressed with it -- look how light and readable the syntax is.

What you've probably figured out already is that each step in JavaScript finds its corresponding step in Markdown by doing a simple string comparison. Simplicity is the best kind of cleverness, wouldn't you say?

Gauge Report

When you run your tests, you end up with a nice-looking report that tells you how many of your specifications passed, and if they failed, which steps caused them to fail.


So, what have we learned?

Frameworks and Unit Testing

Unit testing libraries are still a key part of any responsible developer's toolkit. We want you to continue to use the library of your choice. Gauge doesn't have an opinion on what unit testing library you use, because Gauge is for writing an entirely different category of tests.

Design Thinking starts with empathy.

Gauge wants your step #1 to be empathy. Gauge wants you to think like a user, because they are the ones who will ultimately decide if your web app is acceptable or not.

Gauge home page

Gauge is for writing User Journey tests. Capture the words your end users use, and the steps they take, in plain English Markdown files. Implement the tests in the language of your choice. Show them easy-to-read reports, proving to them that your web app does exactly what they ask it to do.

If you're already writing unit tests, this is your chance to level up and start thinking like a user instead of a developer. Are you up to the challenge?

  This slideshow
  GroceryWorks: a website for a fictional grocery store
  Source code for GroceryWorks
  Source code for Gauge and Taiko User Journey tests for GroceryWorks

Here are links to this slideshow and the source code to GroceryWorks, as well as the associated Gauge and Taiko User Journey tests.

I hope that you've enjoyed getting a brief glimpse of what Gauge and Taiko add to your testing toolkit. Thanks for your time!

Presented by Scott Davis. His email address is His Twitter handle is @scottdavis99.