Module: RSpec::Rails::Matchers

Defined in:
lib/rspec/rails/matchers.rb,
lib/rspec/rails/matchers/be_a_new.rb,
lib/rspec/rails/matchers/be_valid.rb,
lib/rspec/rails/matchers/active_job.rb,
lib/rspec/rails/matchers/redirect_to.rb,
lib/rspec/rails/matchers/base_matcher.rb,
lib/rspec/rails/matchers/be_new_record.rb,
lib/rspec/rails/matchers/have_rendered.rb,
lib/rspec/rails/matchers/have_http_status.rb,
lib/rspec/rails/matchers/routing_matchers.rb,
lib/rspec/rails/matchers/have_enqueued_mail.rb

Overview

Container module for Rails specific matchers.

Defined Under Namespace

Modules: ActiveJob, HaveHttpStatus, RedirectTo, RenderTemplate, RoutingMatchers Classes: BaseMatcher, BeANew

Instance Method Summary collapse

Instance Method Details

#be_a_new(model_class) ⇒ Object

Passes if actual is an instance of model_class and returns true for new_record?. Typically used to specify instance variables assigned to views by controller actions

Use the with method to specify the specific attributes to match on the new record.

Examples:

get :new
assigns(:thing).should be_a_new(Thing)
post :create, :thing => { :name => "Illegal Value" }
assigns(:thing).should be_a_new(Thing).with(:name => nil)
78
79
80
 
# File 'lib/rspec/rails/matchers/be_a_new.rb', line 78
def be_a_new(model_class)
  BeANew.new(model_class)
end

#be_new_record ⇒ Object

Passes if actual returns true for new_record?.

Examples:

get :new
expect(assigns(:thing)).to be_new_record
25
26
27
 
# File 'lib/rspec/rails/matchers/be_new_record.rb', line 25
def be_new_record
  BeANewRecord.new
end

#be_valid(*args) ⇒ Object

Passes if the given model instance's valid? method is true, meaning all of the ActiveModel::Validations passed and no errors exist. If a message is not given, a default message is shown listing each error.

Examples:

thing = Thing.new
expect(thing).to be_valid
44
45
46
 
# File 'lib/rspec/rails/matchers/be_valid.rb', line 44
def be_valid(*args)
  BeValid.new(*args)
end

#have_been_enqueued ⇒ Object

Passes if a job has been enqueued. May chain at_least, at_most or exactly to specify a number of times.

Examples:

before { ActiveJob::Base.queue_adapter.enqueued_jobs.clear }
HeavyLiftingJob.perform_later
expect(HeavyLiftingJob).to have_been_enqueued
HelloJob.perform_later
HeavyLiftingJob.perform_later
expect(HeavyLiftingJob).to have_been_enqueued.exactly(:once)
3.times { HelloJob.perform_later }
expect(HelloJob).to have_been_enqueued.at_least(2).times
HelloJob.perform_later
expect(HelloJob).to enqueue_job(HelloJob).at_most(:twice)
HelloJob.perform_later
HeavyLiftingJob.perform_later
expect(HelloJob).to have_been_enqueued
expect(HeavyLiftingJob).to have_been_enqueued
HelloJob.set(wait_until: Date.tomorrow.noon, queue: "low").perform_later(42)
expect(HelloJob).to have_been_enqueued.with(42).on_queue("low").at(Date.tomorrow.noon)
HelloJob.set(queue: "low").perform_later(42)
expect(HelloJob).to have_been_enqueued.with(42).on_queue("low").at(:no_wait)
303
304
305
306
 
# File 'lib/rspec/rails/matchers/active_job.rb', line 303
def have_been_enqueued
  check_active_job_adapter
  ActiveJob::HaveBeenEnqueued.new
end

#have_enqueued_job(job = nil) ⇒ Object Also known as: enqueue_job

Passes if a job has been enqueued inside block. May chain at_least, at_most or exactly to specify a number of times.

Examples:

expect {
  HeavyLiftingJob.perform_later
}.to have_enqueued_job
# Using alias
expect {
  HeavyLiftingJob.perform_later
}.to enqueue_job
expect {
  HelloJob.perform_later
  HeavyLiftingJob.perform_later
}.to have_enqueued_job(HelloJob).exactly(:once)
expect {
  3.times { HelloJob.perform_later }
}.to have_enqueued_job(HelloJob).at_least(2).times
expect {
  HelloJob.perform_later
}.to have_enqueued_job(HelloJob).at_most(:twice)
expect {
  HelloJob.perform_later
  HeavyLiftingJob.perform_later
}.to have_enqueued_job(HelloJob).and have_enqueued_job(HeavyLiftingJob)
expect {
  HelloJob.set(wait_until: Date.tomorrow.noon, queue: "low").perform_later(42)
}.to have_enqueued_job.with(42).on_queue("low").at(Date.tomorrow.noon)
expect {
  HelloJob.set(queue: "low").perform_later(42)
}.to have_enqueued_job.with(42).on_queue("low").at(:no_wait)
expect {
  HelloJob.perform_later('rspec_rails', 'rails', 42)
}.to have_enqueued_job.with { |from, to, times|
  # Perform more complex argument matching using dynamic arguments
  expect(from).to include "_#{to}"
}
268
269
270
271
 
# File 'lib/rspec/rails/matchers/active_job.rb', line 268
def have_enqueued_job(job = nil)
  check_active_job_adapter
  ActiveJob::HaveEnqueuedJob.new(job)
end

#have_enqueued_mail(mailer_class, mail_method_name) ⇒ Object Also known as: have_enqueued_email, enqueue_mail, enqueue_email

Passes if an email has been enqueued inside block. May chain with to specify expected arguments. May chain at_least, at_most or exactly to specify a number of times. May chain at to specify a send time. May chain on_queue to specify a queue.

Examples:

expect {
  MyMailer.welcome(user).deliver_later
}.to have_enqueued_mail(MyMailer, :welcome)
# Using alias
expect {
  MyMailer.welcome(user).deliver_later
}.to enqueue_mail(MyMailer, :welcome)
expect {
  MyMailer.welcome(user).deliver_later
}.to have_enqueued_mail(MyMailer, :welcome).with(user)
expect {
  MyMailer.welcome(user).deliver_later
  MyMailer.welcome(user).deliver_later
}.to have_enqueued_mail(MyMailer, :welcome).at_least(:once)
expect {
  MyMailer.welcome(user).deliver_later
}.to have_enqueued_mail(MyMailer, :welcome).at_most(:twice)
expect {
  MyMailer.welcome(user).deliver_later(wait_until: Date.tomorrow.noon)
}.to have_enqueued_mail(MyMailer, :welcome).at(Date.tomorrow.noon)
expect {
  MyMailer.welcome(user).deliver_later(queue: :urgent_mail)
}.to have_enqueued_mail(MyMailer, :welcome).on_queue(:urgent_mail)
166
167
168
 
# File 'lib/rspec/rails/matchers/have_enqueued_mail.rb', line 166
def have_enqueued_mail(mailer_class, mail_method_name)
  HaveEnqueuedMail.new(mailer_class, mail_method_name)
end

#have_http_status(target) ⇒ Object

Passes if response has a matching HTTP status code.

The following symbolic status codes are allowed:

  • Rack::Utils::SYMBOL_TO_STATUS_CODE
  • One of the defined ActionDispatch::TestResponse aliases:
    • :error
    • :missing
    • :redirect
    • :success

Examples:

Accepts numeric and symbol statuses

expect(response).to have_http_status(404)
expect(response).to have_http_status(:created)
expect(response).to have_http_status(:success)
expect(response).to have_http_status(:error)
expect(response).to have_http_status(:missing)
expect(response).to have_http_status(:redirect)

Works with standard response objects and Capybara's page

expect(response).to have_http_status(404)
expect(page).to     have_http_status(:created)

Raises:

  • (ArgumentError)

See Also:

375
376
377
378
 
# File 'lib/rspec/rails/matchers/have_http_status.rb', line 375
def have_http_status(target)
  raise ArgumentError, "Invalid HTTP status: nil" unless target
  HaveHttpStatus.matcher_for_status(target)
end