[nongnu] elpa/buttercup 60028db 236/340: docs: Clarify the spy lifespan in writing-tests.md

[ELPA Syncer]

branch: elpa/buttercup
commit 60028dbc34b5ac67b8bdb7c46c7b1d8f6f69de0a
Author: Ola Nilsson <ola.nilsson@gmail.com>
Commit: Ola Nilsson <ola.nilsson@gmail.com>

    docs: Clarify the spy lifespan in writing-tests.md
---
 docs/writing-tests.md | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/docs/writing-tests.md b/docs/writing-tests.md
index 9d6cc54..43a4da5 100644
--- a/docs/writing-tests.md
+++ b/docs/writing-tests.md
@@ -361,9 +361,11 @@ pending in results.
 Buttercup has test double functions called spies. While other
 frameworks call these mocks and similar, we call them spies, because
 their main job is to spy in on function calls. Also, Jasmine calls
-them spies, and so do we. A spy can stub any function and tracks calls
+them spies, and so do we. A spy can stub any function - whether it
+already exists or not - and tracks calls
 to it and all arguments. A spy only exists in the `describe` or `it`
-block it is defined in, and will be removed after each spec. There are
+block it is defined in, and will be activated before and deactivated
+and reset after each spec. There are
 special matchers for interacting with spies. The
 `:to-have-been-called` matcher will return true if the spy was called
 at all. The `:to-have-been-called-with` matcher will return true if
@@ -383,7 +385,21 @@ the argument list matches any of the recorded calls to the 
spy.
    (foo 456 "another param"))
 
   (it "tracks that the spy was called"
-    (expect 'foo :to-have-been-called))
+    (expect 'foo :to-have-been-called)
+    (foo 789))
+
+  (it "resets tracking after each spec"
+    (expect 'foo :not :to-have-been-called-with 789))
+
+  (describe "that is defined in a nested `describe'"
+    (before-each
+      (spy-on 'foo :and-return-value 1))
+    (it "will override any outer spy"
+      (expect (foo 789) :to-equal 1)
+      (expect 'foo :not :to-have-been-called-with 123)))
+
+  (it "will not be active outside it's scope"
+    (expect (foo 789) :to-equal nil))
 
   (it "tracks all arguments of its calls"
     (expect 'foo :to-have-been-called-with 123)