From 16d8ad7849fecc37506dcac34c4f5f7b52533909 Mon Sep 17 00:00:00 2001
From: jbranchaud <jbranchaud@gmail.com>
Date: Thu, 10 Nov 2022 20:57:16 -0600
Subject: [PATCH] Add Run Tests With Documentation Formatting as an RSpec TIL

---
 README.md                                     |  3 +-
 ...run-tests-with-documentation-formatting.md | 39 +++++++++++++++++++
 2 files changed, 41 insertions(+), 1 deletion(-)
 create mode 100644 rspec/run-tests-with-documentation-formatting.md

diff --git a/README.md b/README.md
index ae36d73..b5698b9 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@ pairing with smart people at Hashrocket.
 
 For a steady stream of TILs, [sign up for my newsletter](https://crafty-builder-6996.ck.page/e169c61186).
 
-_1267 TILs and counting..._
+_1268 TILs and counting..._
 
 ---
 
@@ -979,6 +979,7 @@ _1267 TILs and counting..._
 
 - [Check Specific Arguments To Received Method](rspec/check-specific-arguments-to-received-method.md)
 - [Find Minimal Set Of Tests Causing A Flicker](rspec/find-minimal-set-of-tests-causing-a-flicker.md)
+- [Run Tests With Documentation Formatting](rspec/run-tests-with-documentation-formatting.md)
 - [Use Specific Cache Store In A Single Test](rspec/use-specific-cache-store-in-a-single-test.md)
 
 ### Ruby
diff --git a/rspec/run-tests-with-documentation-formatting.md b/rspec/run-tests-with-documentation-formatting.md
new file mode 100644
index 0000000..bdc4bb9
--- /dev/null
+++ b/rspec/run-tests-with-documentation-formatting.md
@@ -0,0 +1,39 @@
+# Run Tests With Documentation Formatting
+
+Typically when you invoke `rspec` on a file or an entire suite of tests, you'll
+see a bunch of dots (`.`) and maybe a couple `F`s.
+
+```
+$ rspec spec/models/user_spec.rb
+
+.F...........
+```
+
+That style of output is called _progress_ formatting.
+
+That's not the only option for formatting output from RSpec. Another one is
+_documentation_ formatting.
+
+Use the `--format` flag to specify a format like `documentation`. Or `-f d`
+works as a shorthand.
+
+```
+$ rspec --format documentation spec/models/user_spec.rb
+
+User
+  #valid?
+    without required fields
+      returns false
+    with invalid email
+      returns false (FAILED - 1)
+    with invalid password
+      too short
+        returns false
+      no upper case letter
+        returns false
+```
+
+The resulting test output is a readable format that leverages the `describe`,
+`context`, and `it` descriptions that we craft for each test.
+
+[source](https://relishapp.com/rspec/rspec-core/v/2-6/docs/command-line/format-option)