Blackbelt Rails Capybara Debugging Techniques (with React Server Rendering)

We’re integrating the react_on_rails gem into the react-webpack-rails-tutorial (pull request #99). While debugging our failing Capybara tests, we came up with the following tips:

  1. Don’t spend too much time thinking, googling, or pondering anything. Get into putting some print statements and seeing what code is doing.

  2. Read any error messages carefully. Often any error messages after the first one are irrelevant.

  3. Clear the rails logs rake log:clear and split your terminal so you tail -f log/test.log as you’re running the test.

  4. Know that some of the messages you see in poltergeist are console messages from the client, and not server messages.

  5. Watch both the logs and the console output for clues to what’s going wrong.

  6. The key is to narrow down the place the error situation is first happening.

  7. Modify the gem’s source, which is located wherever you’re loading your gems. bundle open react_on_rails. Note, we like directly going to the gem source using RubyMine. It’s super easy. See image below.

  8. Add fenced debug statements in your gem source to see what’s going on. See [fenced debugging].(Wrappers on Debug Print Statements)

  9. When a capybara test fails and you’re using capybara_screenshot, be sure to look at both the HTML and PNG of the failure. NOTE: It’s super important to realize that any console messages might be irrelevant because the application.js is not loaded. This is easy mistake to make. See below screenshot. The HTML of what you get in the screenshot is super useful for figuring out the CSS to test for.

  10. Put this in your capybara test
    fail "some message"
    to have capybara-screenshot render a PNG and HTML of the page wherever you put in that fail statement.

  11. Remember that capybara with javascript (aka with Poltergeist) has 2 threads when running a tests. One is running the server code and one is running the browser code.

  12. Don’t forget to run gem pristine <gem name> such as gem pristine react_on_rails to reset the gem after putting in your debug code.

  13. Try to change one thing at a time. In the case of this issue for the react-webpack-rails-tutorial, we changed both the ajax method as well as added server side rendering. We should change one thing at a time!

Example of opening up the capybara failure HTML and seeing red herring log messages (not relevant)

Example of running bundle open

bundle open react_on_rails