From 0a9604d60ba2c21d7e2052a63daded3d3d8770f0 Mon Sep 17 00:00:00 2001
From: John Andrews <john.andrews@joinroot.com>
Date: Tue, 29 Sep 2020 13:44:32 -0400
Subject: [PATCH] Document the process of providing a reason to skip metadata

---
 .../skipped_examples.feature                  | 21 +++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/features/pending_and_skipped_examples/skipped_examples.feature b/features/pending_and_skipped_examples/skipped_examples.feature
index 4ff3c82b28..bbbb351f1c 100644
--- a/features/pending_and_skipped_examples/skipped_examples.feature
+++ b/features/pending_and_skipped_examples/skipped_examples.feature
@@ -110,3 +110,24 @@ Feature: `skip` examples
            # No reason given
            # ./skipped_spec.rb:2
       """
+
+  Scenario: Skipping using metadata with a reason
+    Given a file named "skipped_with_reason_spec.rb" with:
+      """ruby
+      RSpec.describe "an example" do
+        example "is skipped", :skip => "waiting for planets to align" do
+          raise "this line is never executed"
+        end
+      end
+      """
+    When I run `rspec skipped_with_reason_spec.rb`
+    Then the exit status should be 0
+    And the output should contain "1 example, 0 failures, 1 pending"
+    And the output should contain:
+      """
+      Pending: (Failures listed here are expected and do not affect your suite's status)
+
+        1) an example is skipped
+           # waiting for planets to align
+           # ./skipped_with_reason_spec.rb:2
+      """