[nongnu] elpa/buttercup 7e8898b 127/340: Implement :to-have-been-called-times matcher (close #90)

[ELPA Syncer]

branch: elpa/buttercup
commit 7e8898bd6699205ae5c65c8dd7e602a9ed5ab8cd
Author: Damien Cassou <damien@cassou.me>
Commit: Jorgen Schäfer <Jorgen.Schaefer@gmail.com>

    Implement :to-have-been-called-times matcher (close #90)
---
 buttercup.el            | 12 ++++++++++++
 docs/writing-tests.md   | 20 +++++++++++++++++++
 tests/test-buttercup.el | 51 +++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 83 insertions(+)

diff --git a/buttercup.el b/buttercup.el
index 423b675..8b1eb46 100644
--- a/buttercup.el
+++ b/buttercup.el
@@ -617,6 +617,18 @@ KEYWORD can have one of the following values:
      (t
       t))))
 
+(buttercup-define-matcher :to-have-been-called-times (spy number)
+  (let* ((call-count (length (spy-calls-all spy))))
+    (cond
+     ((= number call-count)
+      t)
+     (t
+      (cons nil
+            (format "Expected `%s' to have been called %s %s, but it was 
called %s %s"
+                    spy
+                    number (if (= number 1) "time" "times")
+                    call-count (if (= call-count 1) "time" "times")))))))
+
 (defun spy-calls-any (spy)
   "Return t iff SPY has been called at all, nil otherwise."
   (if (spy-calls-all spy)
diff --git a/docs/writing-tests.md b/docs/writing-tests.md
index 8b965cd..007d1d9 100644
--- a/docs/writing-tests.md
+++ b/docs/writing-tests.md
@@ -359,6 +359,26 @@ the argument list matches any of the recorded calls to the 
spy.
     (expect bar :to-be nil)))
 ```
 
+The `:to-have-been-called-times` matcher will return true if the spy
+was called a certain number of times.
+
+```Lisp
+(describe "A spy"
+  :var (foo bar)
+  (before-each
+   (setf (symbol-function 'foo)
+         (lambda (value)
+           (setq bar value)))
+
+   (spy-on 'foo)
+
+   (foo 123)
+   (foo 456 "another param"))
+
+  (it "tracks that the spy was called twice"
+    (expect 'foo :to-have-been-called-times 2)))
+```
+
 ### Spies: `:and-call-through`
 
 The keyword argument `:and-call-through` to `spy-on` will make the spy
diff --git a/tests/test-buttercup.el b/tests/test-buttercup.el
index b03109f..f591c5e 100644
--- a/tests/test-buttercup.el
+++ b/tests/test-buttercup.el
@@ -556,6 +556,57 @@
                 :to-be
                 t)))
 
+    (describe ":to-have-been-called-times matcher"
+      (before-each
+        (spy-on 'test-function))
+
+      (it "returns error if the spy was called less than expected"
+        (expect (buttercup--apply-matcher
+                 :to-have-been-called-times '(test-function 1))
+                :to-equal
+                (cons nil
+                      "Expected `test-function' to have been called 1 time, 
but it was called 0 times")))
+
+      (it "returns error if the spy was called more than expected"
+        (test-function)
+        (test-function)
+        (expect (buttercup--apply-matcher
+                 :to-have-been-called-times '(test-function 1))
+                :to-equal
+                (cons nil
+                      "Expected `test-function' to have been called 1 time, 
but it was called 2 times")))
+
+      (it "returns true if the spy was called the expected number of times"
+        (test-function)
+        (test-function)
+        (expect (buttercup--apply-matcher
+                 :to-have-been-called-times '(test-function 2))
+                :to-equal t))
+
+      (it "use plural words in error message"
+        (test-function)
+        (test-function)
+        (expect (buttercup--apply-matcher
+                 :to-have-been-called-times '(test-function 3))
+                :to-equal
+                (cons nil
+                      "Expected `test-function' to have been called 3 times, 
but it was called 2 times")))
+
+      (it "use singular expected word in error message"
+        (expect (buttercup--apply-matcher
+                 :to-have-been-called-times '(test-function 1))
+                :to-equal
+                (cons nil
+                      "Expected `test-function' to have been called 1 time, 
but it was called 0 times")))
+
+      (it "use singular actual word in error message"
+        (test-function)
+        (expect (buttercup--apply-matcher
+                 :to-have-been-called-times '(test-function 2))
+                :to-equal
+                (cons nil
+                      "Expected `test-function' to have been called 2 times, 
but it was called 1 time"))))
+
     (describe ":and-call-through keyword functionality"
       (before-each
         (spy-on 'test-function :and-call-through))