One of the best ways to understand any codebase is to read the tests, and Rails is no exception. In this post, we will learn “how to run the tests” included in the Rails codebase.
Specifically, we will learn how to:
- Run the entire Rails test suite
- Run the tests specific to a module
- Run all tests in a file
- Run a single test
The obvious benefit of a test is to make sure that the code still works after making a change. However, another hidden benefit is that a test can help us get familiar with the codebase quickly. You can execute the code without launching the application in the browser or running the complete program. A test allows you to run a specific feature in isolation, which helps you understand the relevant code without worrying about irrelevant details.
Rails puts very high importance on tests. The source code for the framework contains thousands and thousands of high-quality tests that thoroughly test the framework code that hundreds of people contribute to. Understanding tests makes it easy to understand the Rails codebase.
The Rails framework comprises of different frameworks, each of which handles a specific concern related to a web application. For example, ActiveStorage handles the cloud storage, Active Record is the object-relational mapping layer, which maps Ruby objects to tables and records in the database, and so on.
Run the complete Rails test suite
To run all the tests in the entire repository, run the following command from the rails directory.
$ bundle exec rake test
But we are not going to do that, as it may take a while, and for our purpose, which is to understand the Rails source, we need to know how to run a single test, or multiple tests in a file we are trying to understand.
So let’s start by running all the tests in the Action Pack module, a core Rails framework. It contains the source for Rails Controllers and Views, essential parts of any web application.
Running all the tests in a module
We will switch to the Action Pack directory and run the same command to run all tests for this framework.
$ cd actionpack
$ bin/test # or, bundle exec rake test
# Running:
...
Finished in 10.624474s, 330.3693 runs/s, 1565.8187 assertions/s.
3510 runs, 16636 assertions, 0 failures, 0 errors, 0 skips
As you can see, it took about 10 seconds to run all 3500 tests.
Running all the tests in a file
We can go further and run the tests in a specific file that we are trying to understand.
➜ cd actionpack
➜ bin/test test/controller/request_forgery_protection_test.rb
Running 281 tests in parallel using 4 processes
Run options: --seed 1051
# Running:
.........................................................................................................................................................................................................................................................................................
Finished in 2.256050s, 124.5540 runs/s, 425.5225 assertions/s.
281 runs, 960 assertions, 0 failures, 0 errors, 0 skipsRunning a single test
Running all tests in a file is great, but we can also run a single test, which is what we will be doing a lot. To run a single test, run the same command, passing the name of the test:
➜ cd actionpack
➜ bin/test test/controller/request_forgery_protection_test.rb -n test_csrf_token_is_stored_in_cookie
Running 281 tests in parallel using 4 processes
Run options: -n test_csrf_token_is_stored_in_cookie --seed 32363
# Running:
.
Finished in 0.208895s, 4.7871 runs/s, 9.5742 assertions/s.
1 runs, 2 assertions, 0 failures, 0 errors, 0 skipsNow, running the test is only one part of the equation. To understand the source code, we should debug it by putting breakpoints in the source, pausing the execution, and examining the state of the variables at any particular moment in time. We will do that in the next post.
Stay tuned!
