From 6f5184bf01cb67a8b60aca164d011ed283ca4b08 Mon Sep 17 00:00:00 2001
From: YashRE42 <33805964+YashRE42@users.noreply.github.com>
Date: Fri, 12 Apr 2019 00:42:07 +0530
Subject: [PATCH] docs: Explain stubbing for node tests.

---
 docs/testing/testing-with-node.md    | 18 ++++++++++++++++--
 frontend_tests/node_tests/zjquery.js |  7 +++++--
 2 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/docs/testing/testing-with-node.md b/docs/testing/testing-with-node.md
index f85358069f..886a37707c 100644
--- a/docs/testing/testing-with-node.md
+++ b/docs/testing/testing-with-node.md
@@ -64,13 +64,27 @@ Conceptually, the `zjquery` library provides minimal versions of most
 letting you setup return values for more complex functions.  For
 example, if the code you'd like to test calls `$obj.find()`, you can
 use `$obj.set_find_results(selector, $value)` to setup `zjquery` so
-that calls to `$obj.find(selector)` will return `$value`.  See the
-unit test file for details.
+that calls to `$obj.find(selector)` will return `$value`. See the unit
+test file for details.
+
+This process of substituting `jQuery` functions with our own code for
+testing purposes is known as "stubbing". `zjquery` does not stub all
+possible interactions with the dom, as such, you may need to write out
+the stub for a function you're calling in your patch. Typically the stub
+is just placed in the test file, to prevent bloating of `zjquery`
+with functions that are only used in a single test.
+
+A good sign that you need to stub something out is getting an error of
+the type:
+`TypeError: <component>.<method> is not a function`
 
 The `zjquery` library itself is only about 500 lines of code, and can
 also be a useful resource if you're having trouble debugging DOM
 access in the unit tests.
 
+It is typically a good idea to figure out how to stub a given function
+based on how other functions have been stubbed in the same file.
+
 ## Handling dependencies in unit tests
 
 The other big challenge with doing unit tests for a JavaScript project
diff --git a/frontend_tests/node_tests/zjquery.js b/frontend_tests/node_tests/zjquery.js
index 14a41e9a60..84f41b676e 100644
--- a/frontend_tests/node_tests/zjquery.js
+++ b/frontend_tests/node_tests/zjquery.js
@@ -2,7 +2,8 @@
 
 This test module actually tests our test code, particularly zjquery, and
 it is intended to demonstrate how to use zjquery (as well as, of course, verify
-that it works as advertised).
+that it works as advertised). This test module is a good place to learn how to
+stub out functions from jQuery.
 
 What is zjquery?
 
@@ -11,7 +12,9 @@ What is zjquery?
     complexity of jQuery.  It also allows you to mostly simulate DOM for the
     purposes of unit testing, so that your tests focus on component interactions
     that aren't super tightly coupled to building the DOM.  The tests also run
-    faster!
+    faster! Inorder to keep zjquery light, it only has stubs for the most commonly
+    used functions of jQuery. This means that it is possible that you may need to
+    stub out additional functions manually in the relevant test module.
 
 The code we are testing lives here: