Create Approvals test doc (#6821)

* Create Approvals test doc * Apply suggestions from code review Co-Authored-By: Ridhwana <Ridhwana.Khan16@gmail.com> * Update wording Co-authored-by: Ridhwana <Ridhwana.Khan16@gmail.com>
2020-03-24 18:50:02 -04:00 · 2020-03-24 18:50:02 -04:00 · c67a449ec8
commit c67a449ec8
parent 84e84af8d7
2 changed files with 44 additions and 0 deletions
--- a/docs/tests/approvals-tests.md
+++ b/docs/tests/approvals-tests.md
@ -0,0 +1,43 @@
+---
+title: Approvals Tests
+---
+
+# Approvals Tests
+
+Approvals test is a form of unit test. It works by taking a snapshot of the
+results and confirming that they have not changed. A good use-case for the
+Approvals tests is to compare the rendered HTML to the test specified HTML.
+
+## Usage
+
+Simply create your test similar to the following:
+
+```ruby
+it "renders the correct HTML on the home page" do
+  page = '<html><head></head><body><h1>ZOMG</h1></body></html>'
+  verify(format: :html) { page } # format can also be :json
+end
+```
+
+You may then run the said test and a new `*.received.*` file will be created.
+Thereafter, run the following command to verify the newly created file and
+approve the created change.
+
+```shell
+approvals verify
+```
+
+Please be sure to include the Approvals file in your commit.
+
+## Edge cases
+
+Approvals tests are difficult to utilise for testing variables that change. This
+includes variables like:
+
+- Time
+- URL slug
+- uploaded image slug
+
+Please avoid generating large approvals files as it will be stored in the
+codebase. If your approvals file gets too large, Approvals test may not be the
+right tool for the job.
--- a/docs/tests/readme.md
+++ b/docs/tests/readme.md
@ -2,6 +2,7 @@
 title: Testing/QA Guide
 items:
  - acceptance-tests.md
+  - approvals-tests.md
  - integration-tests.md
  - unit-functional-tests.md
  - frontend-tests.md