Adds documentation and feature for job specs

README.md

@@ -321,6 +321,28 @@ end
 For more information, see the [cucumber scenarios for mailer specs
 ](https://relishapp.com/rspec/rspec-rails/v/3-4/docs/mailer-specs).
 
+## Job specs
+
+Tagging a context with the metadata `:type => :job` treats its examples as job
+specs. Typically these specs will live in `spec/jobs`.
+
+```ruby
+require 'rails_helper'
+
+RSpec.describe UploadBackupsJob, :type => :job do
+  describe "#perform_later" do
+    it "uploads a backup" do
+      ActiveJob::Base.queue_adapter = :test
+      UploadBackupsJob.perform_later('backup')
+      expect(UploadBackupsJob).to have_been_enqueued
+    end
+  end
+end
+```
+
+For more information, see the [cucumber scenarios for job specs
+](https://relishapp.com/rspec/rspec-rails/docs/job-specs).
+
 ## View specs
 
 View specs default to residing in the `spec/views` folder. Tagging any context

features/job_specs/job_spec.feature

@@ -0,0 +1,132 @@
+Feature: job spec
+
+  Job specs provide alternative assertions to those available in
+  `ActiveJob::TestHelper` and help assert behaviour of the jobs themselves
+  and that other entities correctly enqueue them.
+
+  Job specs are marked by `:type => :job` or if you have set
+  `config.infer_spec_type_from_file_location!` by placing them in `spec/jobs`.
+
+  With job specs, you can:
+
+  * specify the job class which was enqueued
+  * specify the arguments passed to the job
+  * specify when the job was enqueued until
+  * specify the queue which the job was enqueued to
+
+  Check the documentation on
+  [`have_been_enqueued`](matchers/have-been-enqueued-matcher) and
+  [`have_enqueued_job`](matchers/have-enqueued-job-matcher) for more
+  information.
+
+  Background:
+    Given active job is available
+
+  Scenario: specify that job was enqueued
+    Given a file named "spec/jobs/upload_backups_spec.rb" with:
+    """ruby
+    require "rails_helper"
+
+    RSpec.describe UploadBackupsJob, :type => :job do
+      describe "#perform_later" do
+        it "uploads a backup" do
+          ActiveJob::Base.queue_adapter = :test
+          expect {
+            UploadBackupsJob.perform_later('backup')
+          }.to have_enqueued_job
+        end
+      end
+    end
+    """
+    When I run `rspec spec/jobs/upload_backups_spec.rb`
+    Then the example should pass
+
+  Scenario: specify that job was enqueued for the correct date and time
+    Given a file named "spec/jobs/upload_backups_spec.rb" with:
+    """ruby
+    require "rails_helper"
+
+    RSpec.describe UploadBackupsJob, :type => :job do
+      describe "#perform_later" do
+        it "uploads a backup" do
+          ActiveJob::Base.queue_adapter = :test
+          expect {
+            UploadBackupsJob.set(wait_until: Date.tomorrow.noon, queue: "low").perform_later('backup')
+          }.to have_enqueued_job.with('backup').on_queue("low").at(Date.tomorrow.noon)
+        end
+      end
+    end
+    """
+    When I run `rspec spec/jobs/upload_backups_spec.rb`
+    Then the example should pass
+
+  Scenario: specify that job was enqueued with alias block syntax
+    Given a file named "spec/jobs/upload_backups_spec.rb" with:
+    """ruby
+    require "rails_helper"
+
+    RSpec.describe UploadBackupsJob, :type => :job do
+      describe "#perform_later" do
+        it "uploads a backup" do
+          ActiveJob::Base.queue_adapter = :test
+          expect {
+            UploadBackupsJob.perform_later('backup')
+          }.to enqueue_job
+        end
+      end
+    end
+    """
+    When I run `rspec spec/jobs/upload_backups_spec.rb`
+    Then the example should pass
+
+  Scenario: specify that job was enqueued with imperative syntax
+    Given a file named "spec/jobs/upload_backups_spec.rb" with:
+    """ruby
+    require "rails_helper"
+
+    RSpec.describe UploadBackupsJob, :type => :job do
+      describe "#perform_later" do
+        it "uploads a backup" do
+          ActiveJob::Base.queue_adapter = :test
+          UploadBackupsJob.perform_later('backup')
+          expect(UploadBackupsJob).to have_been_enqueued
+        end
+      end
+    end
+    """
+    When I run `rspec spec/jobs/upload_backups_spec.rb`
+    Then the example should pass
+
+  Scenario: specify that job was enqueued with imperative syntax and a chained expectation
+    Given a file named "spec/jobs/upload_backups_spec.rb" with:
+    """ruby
+    require "rails_helper"
+
+    RSpec.describe UploadBackupsJob, :type => :job do
+      describe "#perform_later" do
+        it "uploads a backup" do
+          ActiveJob::Base.queue_adapter = :test
+          UploadBackupsJob.perform_later('backup')
+          expect(UploadBackupsJob).to have_been_enqueued.exactly(:once)
+        end
+      end
+    end
+    """
+    When I run `rspec spec/jobs/upload_backups_spec.rb`
+    Then the example should pass
+
+  Scenario: the test adapter must be set to :test
+    Given a file named "spec/jobs/upload_backups_spec.rb" with:
+    """ruby
+    require "rails_helper"
+
+    RSpec.describe UploadBackupsJob, :type => :job do
+      describe "#perform_later" do
+        it "uploads a backup" do
+          ActiveJob::Base.queue_adapter = :development
+        end
+      end
+    end
+    """
+    When I run `rspec spec/jobs/upload_backups_spec.rb`
+    Then the example should fail

features/step_definitions/additional_cli_steps.rb

@@ -11,6 +11,11 @@
   step %q{the exit status should be 0}
 end
 
+Then /^the example(s)? should( all)? fail/ do |_, _|
+  step %q{the output should not contain "0 failures"}
+  step %q{the exit status should not be 0}
+end
+
 Given /active job is available/ do
   if !RSpec::Rails::FeatureCheck.has_active_job?
     pending "ActiveJob is not available"