Add Run Tests With Documentation Formatting as an RSpec TIL

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

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)