Adds documentation and feature for job specs (rspec#1725)

* Add documentation for ActiveJob specs

Updates existing documentation with a section on job specs and adds a
related cucumber feature.

* Add failing example for configuration error

Job specs must be set up with the correct queue adapter, otherwise an
exception will be thrown. Adding an additional step definition allows
this scenario to be tested.

* Updates top level documentation for job specs

Applying [PR feedback](rspec#1725 (comment)).

Author: sgerrand

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"