{ "componentChunkName": "component---src-templates-blog-post-tsx", "path": "/blog/2018-06-13-big-testing-in-react/", "result": {"data":{"blogPost":{"title":"Big Testing in React","slug":"/blog/2018-06-13-big-testing-in-react/","authorNodes":[{"name":"Wil Wilsman","slug":"/people/wil-wilsman/"}],"markdown":{"html":"

Does my application work in real life?

\n

This is a big question, and big questions need big answers. How do\nwe answer that question, though? With big tests. When we write and\ndevelop our applications, it's with the intent that somebody will use\nit. We write tests so we can be assured that everything in our app\nworks as expected and is bug free. But how confident are you in your\ntests?

\n

A real person using your app is going to use a real browser; do your\ntests test your app in a real browser? And not everybody uses the same\nbrowser; do your tests test your app across multiple, different\nbrowsers and devices? What about the network? Chances are your app\ntalks to the network, and your tests should account for this too,\nright? Not to mention a person isn't going to interact with your app\non a component level. They're consuming the entire app , using all\nof it together. All of your components working with each other to\ncreate an experience.

\n

If your tests don't test the app in the same way a person would use\nit, how confident can you really be in them?

\n

Where do we even begin to test our apps like this? There are tools\nlike Jest, but those tests don't\nrun in a real browser. There's also Cypress, but\nas of this writing, you currently can't use it outside of\nChrome. There's\nalso a looming thought that \"user tests are slow.\" Do they have to be?

\n

Anatomy of a Big Test

\n

When we talk about testing the entire app in a way that a person would\ninteract with it, we're of course talking about acceptance tests, or\nuser tests, or end-to-end tests. These types of tests have many\nnames, but it all refers to the same process of testing your app as if\nyou were an actual user.

\n

The life of an acceptance test is pretty simple. First, our app is\nmounted and we wait for it to load. Then, some interaction is\nperformed, such as filling out a form, or clicking a button; something\na person would actually do in our app. Finally, we make some\nexpectations about the state of our app after the interaction is\nperformed. Maybe this is a success message, or some other\nconfirmation. If a user does something in our app, they probably\nreceived some feedback. We want to test this interaction and ensure\nthat it works as they would expect it too.

\n

When a person is interacting with your app, they're using their mouse\nand keyboard which is translating to browser events that your app\nresponds to. They're not calling methods and expecting them to return\ncertain values, they're actually clicking things and expecting to\nachieve results. This is what our app's tests should do too: send\nbrowser events and assert that there was feedback.

\n

But how do we actually do all of this?

\n

The Big Setup

\n

Luckily, it's not nearly as hard as it sounds. How we interact with\nour app should be so identical to how our tests interact with our app\nthat the only difference is the entry point.

\n

In development, our entry point imports our app, mounts it, and that's\nit! The app is ready for us to start interacting with. If we're\nworking on a certain feature, we navigate directly to the part of our\napp containing it.

\n

In testing, our entry point imports all of our tests and runs\nthem. It's each test that mounts and interacts with our app. But from\nour app's point of view, nothing is any different than if it were\nbeing interacted with by a person. Only, in our tests, we can reset\nour app when necessary to make sure we're working with a clean state.

\n

Let's get to some actual code! For example's sake, let's say our app\nis built using React and\nWebpack with babel-loader,\nstyle-loader, and\nhtml-webpack-plugin. We'll\nalso be using Mocha and\nChai to write our tests. The app in our\nexample is a simple countdown app that accepts a date input through\nsome custom spinner inputs and displays the time until or elapsed\nsince the specified date.

\n

Here's a quick look at our example app in action (direct\nlink):

\n
\n \n
\n

Our application's entry point looks like this:

\n
// src/index.js\nimport React from 'react';\nimport { render } from 'react-dom';\nimport App from './app';\n\nrender(<App />, document.getElementById('root'));
\n

If you have other necessary app code in your entry point, consider\nmoving it into a reusable module. You could even have a Root\ncomponent with the logic written in lifecycle hooks. The point is:\nduring development, or in production, our app is only mounted once;\nfor our tests, we need to be able to remount our app before each\nscenario.

\n

Our testing entry point will look something like this:

\n
// tests/index.js\n\n// mocha doesn't support es modules, so we import the pre-compiled assets\nimport 'mocha/mocha.js';\nimport 'mocha/mocha.css';\n\n// other setup could be done here too, such as registering chai helpers\nmocha.setup('bdd');\n\n// we import our tests using webpack's require.context\n// if we just use `import`, it will be hoisted above mocha's bdd setup\nconst requireTest = require.context('.', true, /-test/);\nrequireTest.keys().forEach(requireTest);\n\n// run mocha\nmocha.run();
\n

It's each test's job to mount and interact with the app, so all we\nneed to do here is import all of our tests and run them. We'll go over\nwhat our tests will actually look like in just a minute. For now,\nlet's pretend that our tests just do their aforementioned jobs. You\nmight be able to figure out where I'm going since I've been mentioning\nentry points. We're going to use our existing Webpack config to\nbundle our tests.

\n
// webpack.config.js\nmodule.exports = (env) => ({\n  entry: env.testing ? './tests/index.js' : './src/index.js',\n  // ... other webpack config\n});
\n

We're using Webpack v4, which allows us to [export our config as a\nfunction]([Configuration\nhttps://webpack.js.org/configuration/configuration-types/#exporting-a-function). The\nfirst argument of this function, env, is populated by the CLI\nargument of the\nsame name. This way, when we start our app, we can just call yarn\nstart --env.testing to switch to our testing index. This new bundle\nwill run all of our tests for us, and we can open this bundle in any\nbrowser on any device to run our tests there as well!

\n

Note: in our specific case, Mocha's HTML reported requires a\n#mocha container in the DOM to output it's report. We're using\nhtml-webpack-plugin\nalong with\nhtml-webpack-template,\nso we can just change the appMountId of the template when we're in a\ntesting environment.

\n

Okay, so we know how to bundle our tests, but how do we actually\nwrite them?

\n

Writing Big Tests

\n

If we reflect back on our anatomy lesson, our tests do three important\nthings:

\n
    \n
  1. Mount/Remount our app
    2. \n
  2. Interact with our app in a meaningful way
    3. \n
  3. Assert that something happened
    4. \n
\n

To successfully do all of these things, we'll be using a set of\nlibraries developed specifically for testing big. The\nBigTest suite of libraries and framework\nextensions help to answer the big question: does my application work\nin real life? We'll touch on a few of those libraries in the rest of\nthis article, but there are some we won't get to, and more planned for\ndevelopment.

\n

Mounting Our App

\n

First, to mount our app we can just use render from react-dom. But\naccording to the docs: \"If the React element was previously rendered\ninto the container, this will perform an update on it and only mutate\nthe DOM as necessary to reflect the latest React element.\" However,\nthis is not exactly what we want. While this does mount our app, we\nactually want to mount a fresh instance of our app every time. To do\nthis we can combine render and unmountComponentAtNode, which will\ncompletely remove a component from the DOM after calling the\nappropriate lifecycle hooks.

\n

This is pretty simple to do ourselves in our own mount helper, but\nto spare us from even more DIY architecture, we can just utilize the\nhelpers from @bigtest/react\nwhich already do this. It also provides some other useful things, such\nas setting up an in-memory history object for our app to provide to\nReact Router, and\nbinding this history object to other helpers that allow us to navigate\nour app from within our tests.

\n

This is how we would use @bigtest/react to mount our app and visit a\nroute:

\n
import { setupAppForTesting, visit } from '@bigtest/react';\nimport { expect } from 'chai';\n\nimport App from '../src/app';\n\ndescribe('mounting our app and visiting a route', () => {\n  beforeEach(async () => {\n    await setupAppForTesting(App);\n    visit('/2019/01/01');\n  });\n\n  it('shows the date', () => {\n    let $date = document.querySelector('[data-test-countdown-target]');\n    expect($date.textContent).to.equal('January 1st, 2019');\n  });\n});
\n

We can reduce some boilerplate for all of our tests by creating a\nhelper file and combining the React helpers with Mocha hooks. This way\nwe also won't have to import our app into every test file.

\n
// tests/helpers.js\nimport { setupAppForTesting } from '@bigtest/react';\nimport App from '../src/app';\n\nexport { visit, location } from '@bigtest/react';\n\nexport function setupApplicationForTesting() {\n  beforeEach(async function() {\n    this.app = await setupAppForTesting(App);\n  });\n}
\n

We could have other helpers in this file, or do further setup such as\ncreating a mock server. Once we have an easy way for our tests to\nmount our app on demand, we can interact with it.

\n

Interacting With Our App

\n

Again, we're not testing that some function returns some value or\ncalls some other function. We want to interact with our app like a\nreal person would.

\n

To do this, we're going to use\n@bigtest/interactor to\nsend real browser events to our app. I won't go into too much detail\nhere, but interactors are a very powerful, composable, way to interact\nwith the DOM. Interactors will wait for elements to exist before\ninteracting with them, so we don't have to worry about timing our\ntests correctly to sync up with any run loops.

\n

If you're familiar with the page object\npattern, you'll know\nthat they can abstract the internal structure of a page away from the\nuser-facing functionality. They also reduce a lot of boilerplate\naround the UI in our tests, so that if changes are necessary, only the\npage objects need to be updated. You can think of interactors as\ncomposable page objects for modern components.

\n

Let's create an interactor for the custom spinner input in our app:

\n
// tests/interactors/spinner.js\nimport { interactor, clickable, value } from '@bigtest/interactor';\n\nexport default @interactor class SpinnerInteractor {\n  // common helpers provide easy to define interactions\n  prev = clickable('[data-test-spinner-prev]');\n  next = clickable('[data-test-spinner-next]');\n  value = value('input');\n\n  // complex interactions can be expressed as methods\n  select(option) {\n    let self = this;\n\n    // for each letter in `option`, send a keypress event\n    // that will trigger the spinner's typeahead feature\n    for (let key of option) {\n      self = self.trigger('keypress', {\n        charCode: key.charCodeAt()\n      });\n    }\n\n    // methods that return a new instance of itself are chainable\n    return self;\n  }\n}
\n

And we can use this interactor like so:

\n
// interactors are lazy, so we can initialize them without anything\n// actually existing in the DOM yet\nconst year = new SpinnerInteractor('[data-test-year-field]');\n\n// when accessing properties, an error might be thrown if the element does\n// not exist; this can be more useful than typical expectation failures\nexpect(year.value).to.equal('2019');\n//=> Error: unable to find \"[data-test-year-field]\"\n\n// methods return new interactors that can then be chained from one another\nlet selectYear = year.select('2019')\nlet selectYearThenPrev = selectYear.prev();\n\n// interactions do not start until `interactor.run()` is called, or when\n// used with the async/await syntax; they will resolve once the element\n// exists and has been interacted with, or when the timeout ellapses\nawait selectYearThenPrev;\nawait year.next();
\n

We can then take these smaller interactors and compose them to create\nmore complex interactions.

\n
// tests/interactors/form.js\nimport { interactor, scoped } from '@bigtest/interactor';\nimport SpinnerInteractor from './spinner';\n\nexport default @interactor class DateFormInteractor {\n  // the default scope allows us to omit the selector when calling `new`\n  static defaultScope = '[data-test-date-form]';\n\n  // interactors are composable and nested methods return an instance\n  // of the top-most interactor for chaining\n  year = scoped('[data-test-year-field]', SpinnerInteractor);\n  month = scoped('[data-test-month-field]', SpinnerInteractor);\n  day = scoped('[data-test-day-field]', SpinnerInteractor);\n  hour = scoped('[data-test-hour-field]', SpinnerInteractor);\n  minute = scoped('[data-test-minute-field]', SpinnerInteractor);\n  submit = scoped('button[type=\"submit\"]');\n\n  // getters can also be used for computed properties\n  get value() {\n    let date = `${this.year.value}/${this.month.value}/${this.day.value}`;\n    let time = `${this.hour.value}:${this.minute.value}`;\n    return `${date}@${time}`;\n  }\n}
\n

You'll notice our use of data-test-* attributes. This is because, if\nusing element IDs or CSS selectors, updates to the app's design or\nmarkup mean your tests will most likely break. By using data\nattributes, we can make our tests and interactors resilient to future\nchanges. We can also use a babel transform like\nbabel-plugin-remove-jsx-attributes\nto remove our testing attributes in production.

\n

Now that we've successfully set up some interactors, we can use them\nto start interacting with our app in our tests.

\n

Making Assertions About Our App

\n

Making assertions sounds pretty straightforward, but since real apps\ntypically have some async operations associated with them, making\nassertions at the correct time can be cumbersome and\nheadache-inducing.

\n

For example, let's say we need to test that when a user clicks a\nbutton they are shown a random message. When does the message appear\nin the DOM so that we can make an assertion about it? After the user\nclicks, sure, but how long after the user clicks? In React, it's\nwhenever the render loop gets around to rendering that specific\nmessage. What if the app makes a network request for this message\nfirst? Well, now we need to also wait for a response before making our\nassertion.

\n

Interactors wait for elements to exist in the DOM before interacting\nwith them, but can we do the same thing with our assertions? Well, yes\nwe can! Interactors use\n@bigtest/convergence\nunder the hood, and we can utilize convergences for assertions too.

\n

What's a convergence? To put it simply, it's a pure assertion that can\nrun repeatedly until either it passes, or a timeout has been\nexceeded. And pure assertions are expectations that do not cause side\neffects.

\n
import { when } from '@bigtest/convergence';\n\n// will only continue once the expectation is true\nawait when(() => !app.state.isLoading);\n\n// works when throwing errors as well\nawait when(() => {\n  expect(foo).to.equal('bar');\n  expect(baz).to.be.undefined;\n});
\n

Convergent assertions will be called several, maybe even hundreds of\ntimes, depending on the timeout and if the assertion ever passes. So\nhaving side effects in our assertions could cause unintended behavior\nthat may also result in some serious slowdown.

\n

In regard to our tests, if we make sure all of our assertions are all\npure by keeping our interactions inside of hooks, we can use\n@bigtest/mocha to\nautomatically turn all of our it statements into convergences for\nus.

\n
import { describe, beforeEach, it } from '@bigtest/mocha';\nimport { expect } from 'chai';\n\nimport { setupApplicationForTesting, location } from './helpers';\nimport DateFormInteractor from './interactors/form';\n\ndescribe('Date Picker', () => {\n  const form = new DateFormInteractor();\n\n  // for our example app, this function also stubs the date to a constant value\n  setupApplicationForTesting();\n\n  it('defaults to the current date', () => {\n    expect(form.value).to.equal('2018/1/1@0:0');\n  });\n\n  describe('submitting a date and time', () => {\n    beforeEach(async () => {\n      await form\n        .year.select('2019')\n        .hour.select('12')\n        .minute.select('30')\n        .submit.click();\n    });\n\n    // if this fails, @bigtest/mocha's `it` will keep rerunning until it\n    // passes or a timeout has been exceeded\n    it('goes to the date countdown', () => {\n      expect(location().pathname).to.equal('/2019/01/01/12:30');\n    });\n  });\n});
\n

And there we go! We've officially written some big tests that properly\ninteract with our app how a user would.

\n

The Big Finale

\n

Alright, so we've written our tests and we can run them just by\nrunning our app in a testing environment. Our tests interact with our\napp just how a user would, and all of our tests pass with flying\ncolors. But we have real projects with CI/CD pipelines and these tests\nneed to be automatically run, reported, and tracked for us.

\n

Thankfully again, we don't have to do this\nourselves. Karma is a\nframework agnostic test runner that can automatically launch browsers\nand generate reports for us. It has plenty of plugins to work with the\nbrowsers and frameworks we're already using. For our test suite, we're\ngoing to be using\nkarma-webpack,\nkarma-mocha, and\nkarma-mocha-reporter. To\nlaunch our browser, we'll use\nkarma-chrome-launcher.

\n

There are a couple things we need to change first to get our Karma\nplugins working smoothly:

\n
    \n
  1. karma-webpack takes a Webpack config, but will disregard our\nentry and use the file defined in our Karma config instead. This\nmeans some of the testing setup we did in our Webpack config won't\nbe necessary anymore.
    2. \n
  2. karma-mocha will automatically set up Mocha and run our tests for\nus, so we'll need to remove the Mocha imports and initialization we\nmanually did in our testing index.
    3. \n
\n

Our new testing index will now look something like this:

\n
// tests/index.js\n// other setup could be done here too, such as registering chai helpers\nconst requireTest = require.context('.', true, /-test/);\nrequireTest.keys().forEach(requireTest);
\n

And our Karma config will look like this:

\n
module.exports = (config) => {\n  config.set({\n    frameworks: ['mocha'], // sets up the Mocha framework automatically\n    reporters: ['mocha'], // reports back to the CLI formatted like Mocha\n    browsers: ['Chrome'], // automatically launches chrome to run our tests\n\n    files: [\n      // karma-webpack will watch our files\n      { pattern: 'tests/index.js', watched: false }\n    ],\n\n    preprocessors: {\n      // tells Karma that we'll be using Webpack to process this file\n      'tests/index.js': ['webpack']\n    },\n\n    // Mocha reporter options\n    mochaReporter: {\n      showDiff: true\n    },\n\n    // our webpack config exports a function\n    webpack: require('./webpack.config')(),\n\n    // webpack dev middleware options\n    webpackMiddleware: {\n      stats: 'minimal'\n    },\n\n    // for more Karma config options, check out the documentation\n    // http://karma-runner.github.io/2.0/config/configuration-file.html\n  });\n};
\n

With all of that set up, we can run karma start to launch our\nbrowser and automatically start our tests! For our CI/CD integration,\nwe can add the flag --single-run to exit after running our tests in\nthe specified browsers. To add other browsers, we simple just have to\ninstall other launchers like\nkarma-firefox-launcher\nor\nkarma-safari-launcher. We\ncould even use any of the browsers and devices available on\nBrowserStack via\nkarma-browserstack-launcher!

\n
\n

With a little bit of manual setup, and through testing big, we've\nanswered the question: Does my application work in real life?\nHowever, we've only scratched the surface in this article. We glossed\nover some things like convergences and interactors, and we didn't even\nget to touch on server mocking with\n@bigtest/mirage.

\n

Our countdown app lives in the BigTest examples\nrepository\nwhere you can check out the rest of our tests and the entirety of our\nconfiguration files. There will be more examples to come, including\nother frameworks and more complicated test setups. Keep an eye out in\nthe future for more BigTest blog posts and guides, and feel free to\nfollow and contribute to all of the projects over at the BigTest\nGitHub organization.

","frontmatter":{"date":"June 13, 2018","description":"When we write and develop our applications, it's with the intent that somebody will use it. We write tests so we can be assured that everything in our app works as expected and is bug free. But how confident are you in your tests?","tags":["react","open source","bigtest","testing"],"img":{"childImageSharp":{"fixed":{"src":"/static/6b456f27c574350fa94dd270fff6d243/a7715/2018-06-13-big-testing-in-react_bigtest.jpg"}}}}}}},"pageContext":{"id":"9c6207cb-9568-536a-9d26-5e5f5f9a310b"}}, "staticQueryHashes": ["1241260443"]}