Cypress Utilities, APIs, and Troubleshooting

TroubleShooting from the terminal

Cypress also has a command-line tool that allows us 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 run time by default.

When we run this command, we’ll get output directly in our terminal. We’ll get a line for each individual test with a time amount, for example, “✓ marks a group of tickets sold on click 487ms”. We’ll also get a summary table for each file, and a final summary table that gives the time and the test count for each file.

We’ll also get files in tmp/cypress_videos, one for each test file, that shows 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 usually going to be run on a continuous integration server. In actual development, we 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 many different tools to determine what is happening when things don’t work as expected. 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

Logging has always been a big part of the debugging process. Visual debuggers are useful, but being able to send process update messages to the console, like “yep, the code got here” and "the username is Fred", is a powerful way to understand what’s happening in our code. The console in our browser has many helpful tools to make our logs more valuable. Here’s a survey.

The big one 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, the browser usually provides triangle show-hide buttons for the structure of the object. Multiple arguments are printed to the console side by side.

Log also allows us to use string substitution as a replacement for a template string, so we can do either console.log(`` User: ${user}\`` ) or console.log("User: %o", user), where %o is a placeholder for an object. We 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 several similar methods, like debug, error, info, and warn. These methods all behave the exact same way. The browser, however, might choose to use a slightly different style when displaying them. For example, Chrome color-codes error and warn and automatically adds a stack trace to the console when those are used. Browsers typically also allow us to filter based on which method is used to send the message to the console.

Using the console.table

We can get a more structured output with console.table, which takes our arrays, objects, arrays of objects, or objects of arrays and tries to put them in a convenient tabular format in the console.

If we’d prefer a different way to call attention to our message, we can 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. Browsers will vary, of course.

Sometimes all we want to know is whether a particular line is called. The console.count method simply prints out a count, incrementing by one every time it is called. If we 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, we 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.

Using the console.assert

Accessing objects in the Webpacker namespace of our code is tricky. It is recommended to assign an object that we are concerned with to the global object with something like window.object_under_debug = user so we can then access it in the console as object_under_debug. If we want to do some DOM manipulation, $0 provides the object that is currently selected in the DOM element selector part of the browser, and we can also do $("selector") as a shortcut for document.querySelector.

Using the Cypress test runner

Debugging Cypress tests in the Cypress test runner gives us a few more features than browser tools.

In the test runner that 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 we 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 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. We 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. We can download this extension from the extension store of our favorite browser, and it looks something like the screen shown here (this is the Chrome version):