TConsole
NOTE: TConsole isn't compatible with the latest version of MiniTest, and (very sadly) I don't have enough free time to devote to it at the moment. It's a wonderful tool though, so I've every intention of getting it back up and running at some point.
-- Graham Ashton
TConsole is a testing console for Rails. It allows you to issue commands concerning what tests to run, and see their test output. It's also got a helpful reload command for when your Rails environment needs to be restarted.
TConsole should work in pretty much any Unix environment and will work with apps running Ruby 1.9. It can be run on pretty much any test suite that uses MiniTest, including Rails test suites (though MiniTest::Spec isn't supported, unfortunately).
It was written by Alan Johnson, who passed maintainership over to Graham Ashton in July 2013.
See it in Action
There's a quick screencast on Vimeo about TConsole's basic features: Meet TConsole!
Why use TConsole?
- A large amount of time is wasted loading the Rails environment each time you run the Rails testing rake tasks. TConsole loads the environment when you start the console and whenever you reload the environment, but doesn't have to reload the environment for each test execution.
- The Rails rake task syntax
bundle exec rake test:units TEST=test/unit/user_test.rb
can be pretty verbose when you're running specific tests. Yeah, there are tricks you can use to shorten things up, but still, that's crazy long. tconsole lets you just typetest/unit/user_test.rb
to get that specific test file to run. With TConsole you can just typeUserTest
and the test runs! - TConsole makes it dead simple to review how long your tests are taking to run and pinpoint your slowest running tests.
- Re-running failed tests is as easy as typing
!failed
with TConsole.
What about Spork?
Spork's really cool, and it was my primary motivation behind writing tconsole, but I've always felt like having an extra console open for my spork server and another to run my commands is a bit heavy for what I want to do. Beyond that, I couldn't ever figure out how to get Spork to work with test/unit, and since me and DHH are the only two people who still use test/unit I figured it was up to me to come up with something that worked great. If Spork's your cup of tea, though, stop reading this and use what you like.
What about rspec?
We've decided to focus on integrating with MiniTest as tightly as possible, rather than worrying about rspec support.
Installing TConsole
gem install tconsole
Prereleases of TConsole come out pretty frequently. You can install the latest prerelease version with:
gem install tconsole --pre
If you're using bundler, you probably want to simply add TConsole to your Gemfile:
gem "tconsole"
How to use TConsole
In your shell of choice, cd into your Rails project's directory and then
run bundle exec tconsole
to fire up the console. You should see
something like this:
bundle exec tconsole
Loading your Rails environment...
Environment loaded in 7.160264s.
>
Now that you're in the console, let's test out the all
command!
Running all
from the console runs all of your unit, functional, and
integration tests:
> all
Running tests...
Run options:
# Running tests:
....................................................................................
Finished tests in 6.054574s, 6.4999 tests/s, 10.5822 assertions/s.
39 tests, 45 assertions, 0 failures, 0 errors, 0 skips
Test time (including load): 82.806741s
>
If you want to focus in on a particular subset of your tests, like units, functionals, or integration, just enter that keyword:
> units
> functionals
> integration
You can also specify to run all tests in a specific class:
> UserTest
You can dig a bit deeper and just run a particular test in that file as well:
> UserTest#test_that_user_is_healthy
You can list more than just one class or class and method to run, and TConsole will run them all.
> UserTest InvoiceTest SubscriptionTest#test_that_renew_renews_the_subscription
There are a few special ! commands that use data from past test runs.
The !failed
command will rerun the set of tests that failed during the
last run:
> !failed
There's also a !timings
command that will show you a listing of your last test run's test times, sorted to help you
improve slow tests:
> !timings
Timings from last run:
0.042632s PostTest#test_new_post_should_not_be_published
0.033892s PostTest#test_post_should_have_a_title
0.033134s PostsControllerTest#test_can_reach_all_posts
0.007098s PostsControllerTest#test_grabs_posts
0.006212s PostsControllerTest#test_displays_published_posts_by_default
0.006107s PostTest#test_post_cannot_have_an_empty_body
0.002197s PostTest#test_post_should_have_a_publish_date_set_when_published
0.001937s PostTest#test_post_cannot_have_an_empty_title
0.001232s PostTest#test_post_should_have_an_initial_state
0.001128s PostTest#test_post's_state_should_change_when_published
0.001056s PostTest#test_returning_only_published_posts
0.000923s PostTest#test_post_should_have_respond_to_published_appropriately
0.000770s PostTest#test_post_should_have_a_body
You can turn on the Fail Fast feature to cause TConsole to stop running tests as soon as the first test fails. To enable fail fast simply enter:
set fast on
In the console. You can disable Fail Fast again with:
set fast off
If you update your environment, maybe by editing your Gemfile or
changing one of your application's configuration files, you can use the
reload
command to reload the entire environment:
> reload
And then finally, you can run the exit
command to quit:
> exit
Command Line Options
Since TConsole is primarily meant to be run as an interactive console, it doesn't have many command line arguments, but there are a few. TConsole also passes any parameters that it doesn't know through to be run as its initial command. So, for example:
> tconsole all
passes all
through as the first command to be run, so that command
would start TConsole and immediately run all tests. There's a --once
option that can be used if you'd simply like to run a single command by
passing it to the TConsole command in then exit.
The only other TConsole command line option is --trace
. --trace
is
primarily useful for diagnosing problems with TConsole.
Configuration Files
TConsole attempts to load a .tconsole file in your home directory and in your project directory, in that order, to configure your preferred defaults for TConsole. In many situations you won't need to edit your TConsole configuration files to run TConsole, because it includes a sane set of defaults and attempts to auto-detect Rails applications.
Here's a commented example configuration file:
TConsole::Config.run do |config|
# Configures the directory where your tests are located
config.test_dir = "./test"
# Include paths that should be added to Ruby's load path
config.include_paths = ["./test", "./lib"]
# Paths that should be preloaded. You'll have to run the reload
# command to reload these paths in TConsole
config.preload_paths = ["./config/application"]
# File sets are the named sets of files that can be executed. A file
# set named "all" must be included.
config.file_sets = {
"all" => ["test/**/*_test.rb"],
"units" => ["test/units/**/*_test.rb"]
}
# Fail fast specifies whether or not tests should stop executing once
# the first failure occurs.
config.fail_fast = true
# Specifies code to be run before loading the environment
config.before_load do
ENV["RAILS_ENV"] ||= "test"
end
# Specifies code to be run after loading the environment
config.after_load do
::Rails.application
::Rails::Engine.class_eval do
def eager_load!
# turn off eager_loading
end
end
end
# Specifies code to be run before each test execution
config.before_test_run do
puts "I'm about to run!!!"
end
end
Reporting Issues and Contributing
Feel free to report issues in the issue tracker at https://github.com/gma/tconsole/issues. Be sure to include the versions of Ruby, Rails, and your operating system. For bonus points, fork the project and send me a pull request with the fix for the issue you're seeing.
How embarrassing?!?! A testing tool with no tests? At first TConsole was just a bit of experimental code, so test coverage is light. I am working on improving that, though.
License
Copyright (c) 2012 Alan Johnson
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.