Run a Single RSpec Spec File in Ruby

You can run one RSpec file by passing its path directly to the RSpec command. In a project that uses Bundler, the usual command is:

bundle exec rspec spec/db_spec.rb

You will also learn how to run one example by line number, why bundle exec is useful, and how this differs from running the full suite through Rake.

RSpec is a command-line test runner for Ruby. Although a Rake task such as rake spec can be configured to run your entire test suite, RSpec itself accepts file paths as arguments.

That means this command runs only the examples defined in the named file:

rspec spec/db_spec.rb

In projects managed by Bundler, prefer:

bundle exec rspec spec/db_spec.rb

bundle exec runs the version of RSpec and its dependencies declared in the project's Gemfile.lock. This avoids accidentally using a different globally installed version.

Running a single file is important during development because it gives faster feedback. Run the focused test while implementing a change, then run the complete suite before committing or releasing.

Think of the full test suite as every chapter in a book.

• rake spec asks a configured Rake task to read every chapter.
• bundle exec rspec with no file path usually asks RSpec to read every spec it can find.
• bundle exec rspec spec/db_spec.rb opens only the chapter you are currently editing.

You still need to read the whole book eventually, but reading one chapter repeatedly is much faster while revising it.

Pass one or more spec file paths to RSpec:

bundle exec rspec path/to/file_spec.rb

For the example project:

bundle exec rspec spec/db_spec.rb

This runs only the examples in spec/db_spec.rb.

You can also run several selected files:

bundle exec rspec spec/db_spec.rb spec/doc_spec.rb

To run a single example, add the line number where that example or its enclosing group is declared:

bundle exec rspec spec/db_spec.rb:12

For example, given this file:

# spec/db_spec.rb
RSpec.describe Cushion::DB do
  describe "#connected?" do
    it "returns true after connecting" do
      db = described_class.new
      db.connect

      expect(db.connected?).to be(true)
    end
  end
end

If the it block begins on line 3, run it with:

bundle exec rspec spec/db_spec.rb:3

RSpec identifies the example at that line, or an example nested inside the group declared there.

Consider this command:

bundle exec rspec spec/db_spec.rb

And this file:

# spec/db_spec.rb
require "spec_helper"

RSpec.describe Cushion::DB do
  it "starts disconnected" do
    expect(described_class.new.connected?).to be(false)
  end

  it "connects successfully" do
    db = described_class.new
    db.connect

    expect(db.connected?).to be(true)
  end
end

What happens:

1. bundle exec activates the gems locked for this project, including its intended RSpec version.
2. rspec starts the RSpec command-line runner.
3. spec/db_spec.rb tells RSpec which file to load.
4. Ruby executes require "spec_helper", so shared setup from spec/spec_helper.rb is loaded.
5. RSpec registers the Cushion::DB example group and its two examples.
6. RSpec runs those two examples and reports their results.
7. Other files under spec/ are not selected by this command.

If you instead run:

bundle exec rspec spec/db_spec.rb:4

RSpec filters execution to the example associated with line 4: "starts disconnected".

Running selected specs is useful whenever the full suite is slower than the change you are making.

• Editing a database adapter: Run spec/db_spec.rb after each small change to lib/cushion/db.rb.
• Fixing one regression: Run the exact failing example by its file and line number until it passes.
• Working on a feature area: Run a small set of related files, such as request and service specs for one endpoint.
• Investigating flaky tests: Repeat just the affected spec file to reproduce the failure quickly.
• Continuous testing tools: Configure a watcher to rerun the relevant spec file whenever a source file changes.

Focused runs are for fast local feedback. A full test run remains necessary because a change can affect code tested elsewhere.

In real Ruby projects, developers commonly use this progression:

# While changing one behavior
bundle exec rspec spec/db_spec.rb

# While fixing one failing example
bundle exec rspec spec/db_spec.rb:18

# Before creating a commit or pull request
bundle exec rspec

A common workflow is to copy a failing example's location from RSpec output. RSpec often prints failures in a format similar to:

rspec ./spec/db_spec.rb:18

Paste that command into the terminal to rerun only that failure.

Projects may also define Rake tasks as convenient aliases. For example:

# Rakefile
require "rspec/core/rake_task"

RSpec::Core::RakeTask.new(:spec)

task default: :spec

This makes rake spec useful for the full suite, but direct rspec commands are usually clearer for selecting a particular file.

For repeatable subsets of tests, teams often use metadata tags:

it "writes a record", :database do
  # test code
end

bundle exec rspec --tag database

Use a file path when your selection is based on where the test lives; use tags when the selection represents a category across multiple files.

Running rake spec when you want one file

rake spec

This normally invokes the Rake task configured for the whole suite. Use RSpec directly instead:

bundle exec rspec spec/db_spec.rb

Omitting the spec/ directory

If your current directory is the project root, this may not point to the file:

bundle exec rspec db_spec.rb

Use the path relative to the project root:

bundle exec rspec spec/db_spec.rb

Using a global RSpec version by accident

rspec spec/db_spec.rb

This can work, but it may use a globally installed RSpec version that differs from the project version. If the project has a Gemfile, use:

bundle exec rspec spec/db_spec.rb

Using an inaccurate line number

bundle exec rspec spec/db_spec.rb:999

If no example is associated with that line, RSpec may run no examples. Put the line number on an it, specify, or enclosing describe/context declaration.

Assuming a focused file proves the application is safe

A single file can pass while another spec fails due to a shared dependency or changed behavior. Run the full suite before sharing the change:

bundle exec rspec

Treating legacy option files as the command to use

Older RSpec projects may contain spec/spec.opts; modern projects more commonly use .rspec. These files can hold default command-line options, but they do not change the basic idea: pass the spec file path to the RSpec command.

rake spec:doc is not required to run individual files. It is a Rake task name that may or may not be defined by a particular project and RSpec/Rake setup. Direct RSpec commands work in Rails and non-Rails Ruby projects alike.

# One spec file
bundle exec rspec spec/db_spec.rb

# One example or group by line number
bundle exec rspec spec/db_spec.rb:12

# Several selected spec files
bundle exec rspec spec/db_spec.rb spec/doc_spec.rb

# Entire RSpec suite
bundle exec rspec

# Examples with a metadata tag
bundle exec rspec --tag database

# Repeat a focused command while debugging
bundle exec rspec spec/db_spec.rb:12 --format documentation

Rules to remember:

• Give RSpec paths relative to your current directory, usually the project root.
• Use bundle exec when the project uses Bundler.
• A line filter should point to an example or an enclosing example group.
• Run the full suite after the focused tests pass.

How do I run a single RSpec file?

Run RSpec with the file path:

bundle exec rspec spec/db_spec.rb

Can I run one RSpec test by line number?

Yes. Add :LINE_NUMBER after the file path:

bundle exec rspec spec/db_spec.rb:12

Use a line containing an it, specify, describe, or context declaration.

Why should I use bundle exec rspec instead of rspec?

bundle exec uses the gem versions declared for the current project. This prevents conflicts with globally installed gems or another RSpec version.

Does running one spec file require Rails?

No. RSpec accepts file paths in any Ruby project. Rails only adds its own conventions and helper commands.

Why does rake spec run every test?

The spec Rake task is commonly configured to run the complete suite. It is not automatically limited to the file you are editing.

Can I pass more than one spec file to RSpec?

Yes:

bundle exec rspec spec/db_spec.rb spec/doc_spec.rb

Should I run only one spec file before committing?

Use a single file while developing for speed, then run the full suite to catch regressions outside that file.

• RSpec example groups (describe and context) — These organize related examples and can be targeted with a line filter.
• RSpec examples (it and specify) — Individual executable test cases that you can run by file and line number.
• Bundler and bundle exec — Ensures commands use the dependencies locked for the current Ruby project.
• Rake tasks — Project-defined automation commands such as a full test-suite task.
• RSpec metadata and tags — Select tests by category instead of by file location.
• Test isolation — Focused test runs provide rapid feedback, while a full suite checks for wider regressions.
• Ruby require — Spec files commonly require spec_helper to load test configuration and application code.