summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorRobert Speicher <rspeicher@gmail.com>2016-04-01 20:30:24 -0400
committerRobert Speicher <rspeicher@gmail.com>2016-04-01 20:31:16 -0400
commit2e83b562030e078ce6d37f81915590426a57c820 (patch)
treeaa9722a8b63f7aa1adbf9e09c67a2723cd6d36dd
parent60f4081e135bdcd893d60192e652c4b829c656dd (diff)
downloadgitlab-ce-2e83b562030e078ce6d37f81915590426a57c820.tar.gz
Add a section about `let` to the Testing guide
[ci skip]
-rw-r--r--doc/development/testing.md29
1 files changed, 25 insertions, 4 deletions
diff --git a/doc/development/testing.md b/doc/development/testing.md
index 3d1c4ccab47..187d852e533 100644
--- a/doc/development/testing.md
+++ b/doc/development/testing.md
@@ -11,8 +11,7 @@ importance.
## Factories
-GitLab uses [factory_girl] as a test
-fixture replacement.
+GitLab uses [factory_girl] as a test fixture replacement.
- Factory definitions live in `spec/factories/`, named using the pluralization
of their corresponding model (`User` factories are defined in `users.rb`).
@@ -65,8 +64,30 @@ the command line via `bundle exec teaspoon`, or via a web browser at
- Don't `describe` symbols (see [Gotchas](gotchas.md#dont-describe-symbols)).
- Prefer `not_to` to `to_not`.
- Try to match the ordering of tests to the ordering within the class.
-- Try to follow the [Four-Phase Test](https://robots.thoughtbot.com/four-phase-test)
- pattern, using newlines to separate phases.
+- Try to follow the [Four-Phase Test][four-phase-test] pattern, using newlines
+ to separate phases.
+
+[four-phase-test]: https://robots.thoughtbot.com/four-phase-test
+
+### `let` variables
+
+GitLab's RSpec suite has made extensive use of `let` variables to reduce
+duplication. However, this sometimes [comes at the cost of clarity][lets-not],
+so we need to set some guidelines for their use going forward:
+
+- `let` variables are preferable to instance variables. Local variables are
+ preferable to `let` variables.
+- Use `let` to reduce duplication throughout an entire spec file.
+- Don't use `let` to define variables used by a single test; define them as
+ local variables inside the test's `it` block.
+- Don't define a `let` variable inside the top-level `describe` block that's
+ only used in a more deeply-nested `context` or `describe` block. Keep the
+ definition as close as possible to where it's used.
+- Try to avoid overriding the definition of one `let` variable with another.
+- Don't define a `let` variable that's only used by the definition of another.
+ Use a helper method instead.
+
+[lets-not]: https://robots.thoughtbot.com/lets-not
### Test speed