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 $ 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.
$ ruby -I test test/controller/base_test.rb Run options: --seed 42093 # Running: ................... Finished in 0.317563s, 59.8306 runs/s, 157.4491 assertions/s. 19 runs, 50 assertions, 0 failures, 0 errors, 0 skips
If you are wondering what the ‘I’ flag does, we can search the Ruby documentation, which tells us that you can use it to specify the load path, which in this case, is the
$ ruby --help | grep -- -I -Idirectory specify $LOAD_PATH directory (may be used more than once)
Running 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:
$ ruby -I test test/controller/base_test.rb -n test_controller_name # Running: . Finished in 0.217978s, 4.5876 runs/s, 9.1752 assertions/s. 1 runs, 2 assertions, 0 failures, 0 errors, 0 skips
Now, 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.