Skip to content
rspec-command is a helper module for using RSpec to test command-line applications.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
spec Quiet some RSpec warnings. May 6, 2017
.travis.yml Coverage reporting tokens. Mar 6, 2015
.yardopts More yard opts, also make the exclude generic so I can copy-paste bet… Mar 10, 2015
Gemfile First pass on rspec-command. Mar 6, 2015
LICENSE Update Jan 25, 2018
Rakefile Allow running `rake spec[tag]` to select a single tag. Mar 12, 2015
rspec-command.gemspec In case I need pry for debugging. Mar 6, 2015


Build Status Gem Version Coverage Gemnasium License

rspec-command is a helper module for using RSpec to test command-line applications.

Quick Start

Add gem 'rspec-command' to your Gemfile and then configure it in your spec_helper.rb:

require 'rspec_command'

RSpec.configure do |config|
  config.include RSpecCommand

You can then use the helpers in your specs:

require 'spec_helper'

describe 'myapp' do
  command 'myapp --version'
  its(:stdout) { include('1.0.0') }


The core helper is command. It takes a command to run and sets it as the subject for the example group. The command can be given as a string, array, or block. If the command is given as an array, no shell processing is done before running it. If the gem you are running inside has a Gemfile, all commands will be run inside a bundle exec. Each command is run in a new temporary directory so the results of one test won't affect others.

command also optionally takes a hash of options to pass through to Some common options include :input to provide data on stdin and :timeout to change the execution timeout. The option allow_error is not passed through to the underlying ShellOut, but should be set to true to avoid raising an exception if the command fails.

The subject will be set to a Mixlib::ShellOut object so you can use rspec-its to check individual attributes:

describe 'myapp' do
  command 'myapp --version'
  its(:stdout) { include '1.0.0' }
  its(:stderr) { eq '' }
  its(:exitstatus) { eq 0 }


The file method writes a file in to the temporary directory. You can provide the file content as either a string or a block:

describe 'myapp' do
  command 'myapp read data1.txt data2.txt'
  file 'data1.txt', <<-EOH
a thing
  file 'data2.txt' do
    "another thing #{}"
  its(:stdout) { include '2 files imported' }


The fixture_file method copies a file or folder from a fixture to the temporary directory:

describe 'myapp' do
  command 'myapp read entries/'
  fixture_file 'entries'
  its(:stdout) { include '4 files imported' }

These fixtures are generally kept in spec/fixtures but it can be customized by redefining let(:fixture_root).


The environment method sets environment variables for subprocesses run by command:

describe 'myapp' do
  command 'myapp show'
  environment MYAPP_DEBUG: true
  its(:stderr) { include '[debug]' }


The match_fixture matcher lets you check the files created by a command against a fixture:

describe 'myapp' do
  command 'myapp write'
  it { match_fixture 'write_data' }


The capture_output helper lets you redirect the stdout and stderr of a block of code to strings. This includes any subprocesses or non-Ruby output. This can help with integration testing of CLI code without the overhead of running a full subprocess.

The returned object behaves like a string containing the stdout output, but has stdout, stderr, and exitstatus attributes to simulate the object used by command. exitstatus will always be 0.

describe 'myapp' do
  subject do
    capture_output do'show')
  its(:stdout) { include 'Entry:' }


The RSpecCommand::Rake helper is an optional module you can include in your example groups to test Rake tasks without the overhead of running Rake in a full subprocess.

require 'rspec_command'

RSpec.configure do |config|
  config.include RSpecCommand::Rake

describe 'rake myapp' do
  rake_task 'myapp'
  rakefile <<-EOH
require 'myapp'
task 'myapp' do
  its(:stdout) { include 'Initialized new project' }


Copyright 2015, Noah Kantrowitz

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

You can’t perform that action at this time.