RUBYTEST(1)

📦 version 0.2.0, in arch rolling

💖 RUBYTEST(1) — the rubytest girlie manual 💖

okay so bestie, welcome to rubytest(1) — yes that's the section-1 manual page for the rubytest command, and no, we are not skipping anything, we're reading the whole thing together 🫶

✨ NAME ✨

rubytest — ruby test via rubytest api 🌸

💅 DESCRIPTION 💅

The rubytest command is literally the command line interface for running tests for RubyTest-based test frameworks. That's the whole vibe. It's the front door, the main character, the one that actually runs your tests. 👑

🦋 OVERVIEW 🦋

okay so the rubytest command-line tool follows many of the usual conventions, which means using it is fairly straightforward, ngl. The -h/--help option is right there to detail all its options whenever you need a refresher. Here's a basic example of usage, and yes it slays:

$ rubytest -Ilib test/*_test.rb

This would add lib to Ruby's $LOAD_PATH and then load all the test files matching the test/*_test.rb glob. iconic behavior honestly ✨

When running tests, you need to be sure to load in your test framework or your framework's Ruby Test adapter. This is usually done via a helper script in the test files, but might also be done via command line options, e.g.

$ rubytest -r lemon -r ae test/test_*.rb

Of course, it can become tedious having to type such a long command over and over 😭 this is so relatable. This can be dealt with via a configuration file. To utilize, add an etc/test.rb file to a project and add Test.run (an alias for Test.configure) entries to it:

Test.run do |r|
  r.loadpath ´lib´
  r.test_files << ´test/*_test.rb´
end

Test.run ´coverage´ do |r|
  r.loadpath ´lib´
  r.test_files << ´test/*_test.rb´
  r.before do
    require ´simplecov´
    Simplecov.setup do |s|
      s.filter ´test/´
      s.command_name File.basename($0)
      s.coverage_dir ´log/coverage´
    end
    # to ensure proper coverage
    require ´myapp´
  end
end

Now when rubytest is used, the first configuration will apply. To use the ´coverage´ configuration use the -p/--profile option. look at us, being all organized 💅

$ rubytest -p coverage

In this manner a project can have any number of different test configurations, and it is easy to select between them. chef's kiss, fr fr.

⚠️ bestie listen — note that the above example could have used Test.configure instead of Test.run. They do the same thing. But do not use Test.run! because that will cause testing to be run immediately. and like… maybe you want that? but the manpage says don't, so. 🙈

The configuration file can be in the config directory instead of etc, which is nice for Rails projects. But if you prefer a file in the project's root then either Testfile or .test can also be used instead. All of these locations are supported simply because no one configuration convention has taken a solid hold in the Ruby community. However, we highly recommend using etc/test.rb. In the end that seems like the best overall convention. periodt. 🌈

🎀 USAGE 🎀

rubytest [options] [files ...]

🔥 OPTIONS 🔥

  • -p, --profile <NAME> — Use configuration profile.
  • -f, --format <NAME> — Report format.
  • y, --tapy — Shortcut for -f tapy. (yes, y, exactly like that, we don't make the rules 🫶)
  • -j, --tapj — Shortcut for -f tapj.
  • -t, --tag <TAG> — Select tests by tag.
  • -u, --unit <TAG> — Select tests by software unit.
  • -m, --match <TEXT> — Select tests by description.
  • -A, --autopath — Automatically add paths to $LOAD_PATH.
  • -I, --loadpath <PATH> — Add given path to $LOAD_PATH.
  • -C, --chdir <DIR> — Change directory before running tests.
  • -R, --chroot — Change to project root directory before running tests.
  • -r, --require <FILE> — Require file.
  • -c, --config <FILE> — Use alternate config file.
  • -V, --verbose — Provide extra detail in reports.
  • --[no-]ansi — Turn on/off ANSI colors.
  • --debug — Turn on debugging mode.
  • --about — Display information about rubytest.
  • --version — Display rubytest version.
  • -h, --help — Display this help message.

🌟 RESOURCES 🌟

Rubytest is copyrighted open-source software. the legal girlies said what they said:

Copyright (c) 2013 Rubyworks. All rights reserved.

It is redistributable and modifiable in accordance with the terms of the BSD-2-Clause license. 💜

🧚 SEE ALSO 🧚

ruby(1) — go say hi to Ruby's own manual page, she's the blueprint 💖

okay that's the whole page bestie, every last crumb of it 🍓 and just so we're clear, this absolute classic dropped in July 2014 under the RUBYTEST(1) banner — so when you're quoting it to your group chat, cite it right, iykyk 💅✨

📦 where this page comes from