I'm a big fan of end-to-end (E2E) tests. They give me confidence that my system works as a whole..

E2E tests have two goals:

1. Make sure a particular feature works well with all of its connected pieces.
2. Group features together, so one can understand what is going on in the system.

Even though we often use the same tools for writing unit and E2E tests, writing them is different. Unit tests only verify one thing and E2E tests verify multiple things (some implicitly).

A lot of developers find it hard to write and to debug E2E tests.

Here are a couple of tips to help you with writing and maintaining E2E tests.

1) Use data-test to match elements

Use data-test attributes instead of CSS selectors to find elements on pages.

// instead of this
element.find('.description button.expand-button').simulate('click');
// write this
element.find('[data-test="test"]').simulate('click');

Tests often break because the developer didn't know a particular property was used for testing. Having an explicit data-test communicates "this is needed for testing".

I have written about this in more detail before.

2) Verify after every action

In unit tests, you should follow the Four-Phase Test:

setup
action
verify
teardown

Here is an E2E example of that:

setup - create an unpublished blog post

action - visit post edit page
action - select new "published_at" date from date picker
action - submit the form
action - go to index page

verify - post's "published_at" is changed
verify - the post is shown on page

However, in E2E, if we only verify in the end, we might miss an error that happens somewhere in the middle. For example, a validation error might occur. A better approach is to do the following:

setup - create an unpublished blog post

action - visit post edit page
verify - the post is shown on the edit page

action - select new "published_at" date from date picker
verify - the correct date selected from the date picker

action - submit the form
verify - no errors and success message is shown
verify - post's "published_at" is changed

action - go to index page
verify - the post is shown on page

In this way, if the date picker fails, we will know immediately instead of having to hunt down why the unpublished post is not shown on the index page.

Many assertions are already made by your testing library of choice - like click_link "foo" failing if it can't find what it's looking for. But there might be gaps when you have custom components, and you could make your own checks for those.

3) Write helpers for custom operations

Often in E2E, you have to perform a group of related operations. It is useful to have shared helpers for those.

For example, if you have a fancy calendar picker. Every time you use it, you will have to write the following:

- click data-test="calendar-picker"
- enter the correct year in a text input
- pick a correct month from month picker
- click on the correct day
- click the "ok" button to save

It makes a lot more sense to have a single helper function, so when you change "ok" with "done", you can do it in one place.

Helpers.selectInCalendarPicker(date)

Here are some other examples for grouping operations:

Helpers.loginAs(user)
Helpers.enterCommentWith(text)
Helpers.submitCommentWith(text)
Helpers.closeModal()
Helpers.enterInForm(values)

You can hide your verify checks in those helpers.

This is essential to have a maintainable E2E test suite. Ideally, a good test should read like a story and its implementation details would be hidden.

4) Wait for Ajax

Often you have an Ajax call, followed by an assertion. Those calls take time and can lead to timeouts.

I always have a waitForAjax helper in my projects:

await Helper.waitForAjax();

Here is a sample implementation with Apollo and Cypbara:

import { ApolloLink, concat } from 'apollo-link';
import { environment } from '~/config';

let recordRequestsInFlight = (networkLink) => networkLink;

if (environment.isBrowser && environment.isTest) {
  recordRequestsInFlight = (networkLink) => {
    const recorderLink = new ApolloLink((operation, forward) => {
      window.test.apolloRequestsInFlight += 1;
      
      return forward(operation).map((result) => {
        window.test.apolloRequestsInFlight -= 1;
        return result;
      });
    });
    return concat(recorderLink, networkLink);
  };
}

// Usage
new ApolloClient({
 link: recordRequestsInFlight(
   new HttpLink(/* ... */),
 ),
 // ...
});

# this waits until there are no upcoming XHR request
def wait_for_ajax
  Timeout.timeout(Capybara.default_max_wait_time) do
    loop while page.evaluate_script('window.test.hasInFlightRequests()')
  end
rescue Timeout::Error
  # NOTE(rstankov): Some times this fails on CI while code is working
  nil
end

Code in Gist

Conclusion

Those tips are valid independently if you test with Cypbara, Cypress or XCTest or similar. Their goal is to make your tests more reliable and easy to write, so you can spend more time developing your features instead of hunting for brittle tests.

If you have any questions or comments, you can ping me on Twitter.

One of the barriers to entry for writing tests is the "ergonomics" of our tools. Requiring too much ceremony or boilerplate for every test will put off even the most enthusiastic testers.

One of the reasons testing is common in Ruby land is tools do a lot of the setup/tear down for you. A lot of this comes from tight integration of libraries like Rails, RSpec, FactoryBot.

In JavaScript land, things are decoupled, and you need to do too much setup/configuration.

To have a sound testing story, you need to build your testing tools to integrate the different parts. Writing tests should be frictionless so that you can focus only on testing logic.

The second friction point in testing is speed - If it's faster to run the test, I'll do it more often. Having to wait makes you test less frequently. The best tooling investment I ever did is integrate vim-test and run the current test from my editor with a simple shortcut.

When I'm writing test, I have a couple of goals:

• keep tests simple and understandable
• only test the important characteristics
• try to make future-proof as possible

Here are some of the tricks, I use to accomplish those goals.

Most of the components, I write follow the "Component Folder Pattern". Where I have something like the following:

/components/CustomComponent/index.js - component itself
/components/CustomComponent/index.test.js - test file
/components/CustomComponent/styles.css - styles for this compoennt
/components/CustomComponent/SubComponent.js - any subcompoennts
/components/CustomComponent/Fragment.graphq - GraphQL fragment
/compoennts/CustomComponent/... - other things related to this component

I like this pattern a lot. Especially for tests, since you can find the unit test for a specific component quite easy. One other benefit is that, when you rename the component you don't have to rename its test file.

My tests usually look something like this:

// I don't use  the actual component name, in this way 
// when you rename the component, no test change is required
import Component from './index'; 

// future proving, I use `Component.name`, 
// so your test always show the correct component name
// (this works for normal functions as well)
describe(Component.name, () => {
   // I use SUD (system under test) wrapper component for the tests
   // in this way each test contains only the props, specific to a test case
   const defaults = {
     // some default properties
   };
   const SUD = (props) => <Component {...defaults} {...props} />;
   
   it('renders something when someProp is given', () => {
     // this test only cares about `someProp`
     const wrapper = render(<SUD someProp={"value"} />);
     // ... rest of the test
   });
});

I format my it test description in the following format:

it('[action]')
it('[action] when [condition]')
it('can [action] when [condition'])

Here are some examples:

it('renders a form')
it('renders error messages when invalid data is given')
it('can submit a form when valid data is given')

If you want to learn more about the terminology you can check out the slides from my recent talk "Testing in Javascript" at Tech Talks.

When testing HTML components, I often see people using class names as selectors. For example:

element.find('.description button.expand-button').simulate('click');

While this seems convenient at first, there are some drawbacks. HTML structure and css classes tend to change due to design changes. Which will cause you re-write tests quite often. Also, if you are using css-modules you can't rely on class names.

Because of that, for quite some time now, I have started marking elements with data-test attribute.

React example (using enzyme and chai-enzyme):

describe(Description.name, () => {
  it('cut off text based on `cutoffLength`', () => {
    const el = shallow(<Description text="test" cutoffLength={1} />);
    
    expect(el).to.have.text('t...');
    expect(el).not.to.have.text('test');
  });

  it('hides expand button when text is short', () => {
    const el = shallow(<Description text="test" cutoffLength={10} />);
    expect(el).not.to.have.descendants('[data-text="expand-button"]');
  });

  it('shows expand button when text is long', () => {
    const el = shallow(<Description text="test" cutoffLength={1} />);
    expect(el).to.have.descendants('[data-test="expand-button"]');
  });

  it('clicking expand button reveals the whole text', () => {
    const el = shallow(<Description text="test" cutoffLength={1} />);

    el.find('[data-test="expand-button"]').simulate('click');

    expect(el).not.to.have.descendants('[data-test="expand-button"]');
    expect(el).to.have.text('test');
  });
});

The component code:

import React from 'react';
import styles from "./style.css";

export default Description extends React.Component {
  state = { expanded: false };

  render() {
    const { text, cutoffLength } = this.props;

    if (this.state.expanded || text.length < cutoffLength) {
      return (
        <div className={styles.description}>
          {this.props.text}
        </div>
      );
    }

    return (
      <div className={styles.description}>
        {`${ text.substr(0, cutoffLength) }...`}
        <button 
          data-test="expand-button" 
          className={styles.expand} 
          onClick={this.expand}>show more</button>
      </div>
    );
  }

  expand = () => {
    this.setState({ expanded: true });
  };
}

I'm also using data-test attributes for testing with Capybara in Ruby land.

describe 'Product page' do
  it 'has product description rev' do
    product = create :post, :with_long_description

    visit product_path(product)

    expect(page).not_to have_text product.description

    # This can be extracted into `find_test_attr` or `click_test_attr`
    find(:css, '[data-test="expand"]').click

    expect(page).to have_text product.description

    # This can be extracted into `have_test_arr`
    expect(page).not_to have_css('[data-test="expand"]')
  end
end