[Fixes #15951] Document JS test suite basics

X-Ref: #15953
Closes #15952 by merging a tweaked version of it.
[skip sauce]
[skip validator]

README.md

@@ -91,7 +91,7 @@ Documentation for v2.3.2 has been made available for the time being at <http://g
 
 Please read through our [contributing guidelines](https://github.com/twbs/bootstrap/blob/master/CONTRIBUTING.md). Included are directions for opening issues, coding standards, and notes on development.
 
-Moreover, if your pull request contains JavaScript patches or features, you must include relevant unit tests. All HTML and CSS should conform to the [Code Guide](https://github.com/mdo/code-guide), maintained by [Mark Otto](https://github.com/mdo).
+Moreover, if your pull request contains JavaScript patches or features, you must include [relevant unit tests](https://github.com/twbs/bootstrap/tree/master/js/tests). All HTML and CSS should conform to the [Code Guide](https://github.com/mdo/code-guide), maintained by [Mark Otto](https://github.com/mdo).
 
 Editor preferences are available in the [editor config](https://github.com/twbs/bootstrap/blob/master/.editorconfig) for easy use in common text editors. Read more and download plugins at <http://editorconfig.org>.
 

js/tests/README.md

@@ -0,0 +1,61 @@
+## How does Bootstrap's test suite work?
+
+Bootstrap uses [QUnit](http://api.qunitjs.com/), a powerful, easy-to-use JavaScript unit test framework. Each plugin has a file dedicated to its tests in `unit/<plugin-name>.js`.
+
+* `unit/` contains the unit test files for each Bootstrap plugin.
+* `vendor/` contains third-party testing-related code (QUnit and jQuery).
+* `visual/` contains "visual" tests which are run interactively in real browsers and require manual verification by humans.
+
+To run the unit test suite via [PhantomJS](http://phantomjs.org/), run `grunt test-js`.
+
+To run the unit test suite via a real web browser, open `index.html` in the browser.
+
+
+## How do I add a new unit test?
+
+1. Locate and open the file dedicated to the plugin which you need to add tests to (`unit/<plugin-name>.js`).
+2. Review the [QUnit API Documentation](http://api.qunitjs.com/) and use the existing tests as references for how to structure your new tests.
+3. Write the necessary unit test(s) for the new or revised functionality.
+4. Run `grunt test-js` to see the results of your newly-added test(s).
+
+**Note:** Your new unit tests should fail before your changes are applied to the plugin, and should pass after your changes are applied to the plugin.
+
+## What should a unit test look like?
+
+* Each test should have a unique name clearly stating what unit is being tested.
+* Each test should test only one unit per test, although one test can include several assertions. Create multiple tests for multiple units of functionality.
+* Each test should begin with [`assert.expect`](http://api.qunitjs.com/expect/) to ensure that the expected assertions are run.
+* Each test should follow the project's [JavaScript Code Guidelines](https://github.com/twbs/bootstrap/blob/master/CONTRIBUTING.md#js)
+
+### Example tests
+
+```javascript
+// Synchronous test
+QUnit.test('should describe the unit being tested', function (assert) {
+  assert.expect(1)
+  var templateHTML = '<div class="alert alert-danger fade in">'
+      + '<a class="close" href="#" data-dismiss="alert">×</a>'
+      + '<p><strong>Template necessary for the test.</p>'
+      + '</div>'
+  var $alert = $(templateHTML).appendTo('#qunit-fixture').bootstrapAlert()
+
+  $alert.find('.close').click()
+
+  // Make assertion
+  assert.strictEqual($alert.hasClass('in'), false, 'remove .in class on .close click')
+})
+
+// Asynchronous test
+QUnit.test('should describe the unit being tested', function (assert) {
+  assert.expect(1)
+  var done = assert.async()
+
+  $('<div title="tooltip title"></div>')
+    .appendTo('#qunit-fixture')
+    .on('shown.bs.tooltip', function () {
+      assert.ok(true, '"shown" event was fired after calling "show"')
+      done()
+    })
+    .bootstrapTooltip('show')
+})
+```