📝 Docs: Explanation of running tests in browser lacks details, full working source code

[wmakley]

I've been trying very hard to make this do something: https://mochajs.org/#running-mocha-in-the-browser. There isn't enough information for a beginner to fully understand what is going on, and I'm trying to make a list of all the questions I had.

1. The tests are not included.
2. How would I run the examples without a CDN? Even though I am using a browser, there is no guarantee that a CDN is available or will continue to be available in the future, or that I even have a network connection.
3. What are the non-Mocha CDN libraries for? Are they required?
4. How do I indicate to Mocha where my test files are and which ones to run?
5. Ideally I would like my tests to be runnable both in the browser and from the console. Is this possible?

Can these script tags have some more explanation? Up until now, this naming scheme has not been introduced in the documentation. What is the contents of these files?

<script src="test.array.js"></script>
<script src="test.object.js"></script>
<script src="test.xhr.js"></script>

[ScottFreeCode]

• The files with the "test.....js" names are the answer to 4: you simply include your test files as script tags like that. They can be named whatever you want; these names are just trying to convey that these are examples of test files.
• Re. 2, the Mocha script and CSS can be taken from a local copy of Mocha such as an NPM install. Frankly I'd be inclined to document node_modules instead and let people who want to use CDNs or other installation methods figure out the right path for their approach -- the relationship between a CDN and NPM installs is well known by people using NPM packages through CDNs but not as well known to newcomers, so...
• Re. 3: I think jQuery is there partly to provide an example of the mocha.globals use case so that an example of mocha configuration in the browser can be given, and it's a hypothetical module that could be used by the tests -- in your code it might be replaced by the library you're testing; expect.js is an assertion library. Loading these libraries as globals allows the tests to use them without requireing them (see below).
• Re. 5, if your test files don't require anything themselves (instead setting up the globals they need via --require in Node and preceding script tags in the browser), then they will run fine in the browser (and in Node). Otherwise, you will probably have to look into module loading systems that can be used in the browser and/or in Node, and/or try bundling the test files.

The example is, admittedly, rather bare-bones -- it doesn't get into half the things that can be involved in actually using Mocha in a browser scalably, just tries to demonstrate the essentials... But it could probably do with more accompanying explanation of what little it does demonstrate.

[stale]

I am a bot that watches issues for inactivity.
This issue hasn't had any recent activity, and I'm labeling it stale. In 14 days, if there are no further comments or activity, I will close this issue.
Thanks for contributing to Mocha!

[grahamlyons]

I came up against this looking for a simple, browser-based testing library. Mocha looked like a more up-to-date QUnit (sorry QUnit) but the browser looked out of date so I tried to update the version in the URL but it appears that mocha.js isn't included in releases any more.

If Mocha isn't going to support simple browser testing any more then it would be good to update the docs to reflect that. If it is, then having mocha.js included would aid the quickstart process.

[outsideris]

@grahamlyons We still include mocha.js which built from script.
You can use it like https://unpkg.com/mocha@5.0.5/mocha.js .

[grahamlyons]

Aha! That's really useful. Thank you, @outsideris.

[JoshuaKGoldberg]

Moved over to mochajs/mocha-examples#80, which has an existing PR at mochajs/mocha-examples#72. Cheers all!