branch: elpa/buttercup
commit d8b596c59907994924ec3890f3d6579ec8a72c93
Merge: b2edd35 818c150
Author: Ola Nilsson <ola.nils...@gmail.com>
Commit: Ola Nilsson <ola.nils...@gmail.com>
Merge branch 'doc-improve'
* doc-improve:
docs: Clarify the difference between :var and `let'
Update some docstrings
test: Add missing apostrophe in spec title
docs: Clarify the spy lifespan in writing-tests.md
---
buttercup.el | 6 ++++--
docs/writing-tests.md | 26 +++++++++++++++++++++++---
tests/test-buttercup.el | 2 +-
3 files changed, 28 insertions(+), 6 deletions(-)
diff --git a/buttercup.el b/buttercup.el
index fecc932..c3bec14 100644
--- a/buttercup.el
+++ b/buttercup.el
@@ -205,11 +205,13 @@ failed."
,@body)))
(defun buttercup--function-as-matcher (fun)
+ "Wrap FUN in code to unpack function-wrapped arguments."
(cl-assert (functionp fun) t)
(lambda (&rest args)
(apply fun (mapcar #'funcall args))))
(defun buttercup--find-matcher-function (matcher)
+ "Return the matcher function for MATCHER."
(let ((matcher-prop
(when (symbolp matcher)
(get matcher 'buttercup-matcher))))
@@ -1211,7 +1213,7 @@ responsibility to ensure ARG is a command."
buttercup--spy-contexts))
(defun buttercup--spy-calls-add (spy-function context)
- "Add CONTEXT to the recorded calls to SPY."
+ "Add CONTEXT to the recorded calls to SPY-FUNCTION."
(puthash spy-function
(append (gethash spy-function
buttercup--spy-contexts)
@@ -1720,7 +1722,7 @@ FMT and ARGS are passed to `format'."
(defadvice display-warning (around buttercup-defer-warnings activate)
- "Log all warnings to a special buffer while running buttercup tests.
+ "Log all warnings to a special buffer while running buttercup specs.
Emacs' normal display logic for warnings doesn't mix well with
buttercup, for several reasons. So instead, while a buttercup
diff --git a/docs/writing-tests.md b/docs/writing-tests.md
index 9d6cc54..8ff86e0 100644
--- a/docs/writing-tests.md
+++ b/docs/writing-tests.md
@@ -226,6 +226,10 @@ It's important to note that `lexical-binding` must be
`non-nil` for
`:var` and `:var*` to work properly. Within a test file this is
usually set using a local file variable.
+Using `:var` and `:var*` works just like the `let` equivalents, but
+it's recommended to use the `:var` format to be future proof. Future
+internal changes in `buttercup` could break suites using `let`.
+
### Setup and Teardown
To help a test suite DRY up any duplicated setup and teardown code,
@@ -361,9 +365,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 +389,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)
diff --git a/tests/test-buttercup.el b/tests/test-buttercup.el
index 6368202..03aa6bb 100644
--- a/tests/test-buttercup.el
+++ b/tests/test-buttercup.el
@@ -1091,7 +1091,7 @@
(expect 'reporter :to-have-been-called-with 'buttercup-started
buttercup-suites)
(expect 'reporter :to-have-been-called-with 'buttercup-done
buttercup-suites)))
)
- (it "should call `buttercup--run-suite once per suite"
+ (it "should call `buttercup--run-suite' once per suite"
(let ((buttercup-suites (list parent-suite)) runner)
(ignore runner)
(setf (symbol-function 'runner) (lambda (suite) (ignore suite)))
