Cypress Utilities, APIs, and Troubleshooting

Cypress also has a command-line tool that allows you to run Cypress from a terminal or from a command line in a continuous integration tool. In our environment, we start that tool with rake cypress:run. Doing so will run the tests against the Electron JS runtime by default.

If you run this command, you’ll get output directly In your terminal. You’ll get a line for each individual test with a time amount (for example, ✓ marks a group of tickets sold on click (487ms)), you’ll get a summary table for each file, and you’ll get a final summary table that gives the time and test count for each file.

You will also get files in tmp/cypress_videos, one for each test file, that show a video capture of the browser for each test in the file. A failing test adds a screenshot of the failure into the folder tmp/cypress_screenshots.

This command is probably mostly going to be run on a continuous integration server. In actual development, you may want the interactive test runner and access to the browser tools.

Troubleshooting

Sometimes things just don’t work the way you expect, either when testing your code in Cypress or when just running it in the browser. Browsers have a lot of different tools to allow you to explore what is happening. We’ll take a look at those tools first, then look at debugging Cypress tests in the Cypress test runner. We’ll end by taking a quick peek at a browser extension to troubleshoot React components.

Using the console log

If you are me, logging has always been a big part of your debugging flow. Visual debuggers are nice, but being able to send “yep, the code got here” and "the user name is Fred" messages to the console are pretty powerful ways to understand what’s going on in your code. The console in your browser has a lot of helpful tools to make your logs more valuable. Here’s a survey.

The big one, of course, is console.log, which takes an arbitrary number of arguments and prints them to the console. If the argument is an object or an array, usually the browser provides triangle show-hide buttons for the structure of the object. Multiple arguments are printed to the console side by side.

Log also allows you to use string substitution as a replacement for a template string, so you can do either console.log(\User: ${user}\) or console.log("User: %o", user), where %o is a placeholder for an object—you also have %s for strings and %i or %f for numbers. The template strings are usually shorter, but some browsers display objects better using the string substitution method.

The log method has a bunch of friends: debug, error, info, and warn. These methods all behave the exact same; however, the browser might choose to use a slightly different style when displaying them. For example, Chrome color-codes error and warn, and also automatically adds a stack trace to the console when those are used. Browsers typically also allow you to filter based on which method is used to send the message to the console.

You can get more structured output with console.table, which takes your arrays, objects, arrays of objects, or objects of arrays and tries to put them in a convenient tabular format in the console. I need to remember to use this one more—it’s quite useful.

If you’d like a different way to call attention to your message, you can actually embed CSS into the call using string substation and a %c, as in console.log("%c user: %o", "font-size: 24pt; color: green", user). Most text-based CSS will work here; again, browsers will vary.

Sometimes all you want to know is whether a particular line is called, and you don’t really have a message. The console.count method just prints out a count, incrementing by one every time it is called. If you give count an argument, that argument is displayed with the count as tag, and count maintains a separate value for each tag. The method countReset resets the count back to zero and may or may not display a 0 message depending on the browser.

Often you only want a message to appear in the console conditionally. The method, console.assert takes two arguments: a boolean expression and a string. The method only displays the string if the assertion is false. Again, different browsers will display the assertion failure differently.

Accessing objects in the Webpacker namespace of your code is a little tricky. I recommend explicitly (and temporarily) assigning an object that you are concerned about to the global object with something like window.object_under_debug = user, and then you can access it in the console as object_under_debug. If you want to do some DOM manipulation, $0 provides the object that is currently selected in the DOM element selector part of the browser, and you can also do $("selector") as a shortcut for document.querySelector.

Using the Cypress test runner

Debugging Cypress tests in the Cypress test runner gives you a few additional features than browser tools.

Just in the test runner itself, which we saw earlier in the screenshot, clicking on any of the command steps in the left-hand column displays the result of that step in the console where you can examine it more closely. Similarly, clicking on error messages on the left side will put the error stack trace in the console.

The cy.log command takes a string message and an arbitrary object. When invoked, it prints the message and the object to the left-side command rundown of the test runner, and clicking on that message puts the arbitrary object into the console. This can be a helpful way to log messages in tests and have them be displayed in the context of the code that displays the message.

Also, right above the actual browser display is a text bit that starts with cy.get or something similar. This is a little UI for interacting with the browser on display. ou can enter a Cypress finder method at the top, see the result of that selector highlighted in the document, and print it to the console.

Using the React DevTools extension

A few React-specific troubleshooting tools are worth becoming familiar with, too. The most important is a browser extension called React DevTools. You can download this extension from the extension store of your favorite browser, and it looks something like this (this is the Chrome version):