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: . 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: