Improve README usefulness

[dasilvacontin]

• why mocha vs other js test frameworks? differences
• getting started with testing and mocha
• simple example maybe?
• how to contribute / how to get started contributing
• etc (suggest; specially if you personally found something lacking)

[ScottFreeCode]

• 📝 Docs: Document hooks better #2209 requested more thorough examples of the different interfaces.
• Document that the exports interface can't be used in the browser directly, since it is... well, module-based. (Discussion at Interface "exports" not working in browser #2198, including a plugin I put together that should allow it to be used with AMD modules, although there might be edge cases I haven't run into yet. Amusingly, you can tell from my running exploration there that I discovered AMD modules in the middle of April, presumably between the 11th and the 14th.)

[dasilvacontin]

• explain what karma, mocha and chai.js are. Beginners are not familiar with the concepts of test runner, test framework and assertion library.

[ScottFreeCode]

• We've already got good documentation of async hooks and the delay option, yet we continue to get requests for a before-describe hook... Is there a way to increase the discoverability of the existing documentation?
• Then again, those examples show a certain disparity -- the async hooks one assumes you're familiar with or able to figure out the particular database API used, the delay one uses a contrivedly simple demonstration with setTimeout; ideally, both would be somewhere in between, trivial to understand but not just contrived.
• Double-check that documentation is not misleading re. local vs. global installation, per Mocha isn't running when installed locally... #291 (comment)
• We get occasional questions about use with ES6; the docs currently mention that --compilers can be used for Coffeescript and don't elaborate on anything else in that regard.
• We get occasional confusion about only really being an alternative way to grep. I can make a case that only should be changed in a future backwards-incompatible version, but until then, let's document this behavior under both grep (both commandline and in-browser) and only.
• mocha.grep(...) is undocumented.
• "Pending Tests" and "Inclusive Tests" (that is, skipped tests; tangentially, "inclusive" doesn't make much sense to me as a name for it in and of itself -- it only kinda sorta makes sense by way of contrast with only being "exclusive tests"), which are very similar on a technical level (although serving distinct purposes -- one is "let's write this later" and another is "this is written, but we need to avoid running it in some or all cases"), are on either side of "Exclusive Tests" (only) instead of next to each other. We should consider whether that's a good thing or a bad thing.
• If there's a programmatic API parameter for watch, make sure it's documented, per Watch from programmatic API #2293.
• Docs about timeout for hooks #2296 is about documentation for setting timeout in hooks.

...Those are all the other issues I could find relating to (or suggesting need of) documentation.

We should probably consolidate these into a single list in the OP (with editting out of any inapplicable ones if necessary).

[ScottFreeCode]

• Document ?fgrep=automatically escaped partial match browser grep variation.

[ScottFreeCode]

We should have someplace people are encouraged to list integrations with other frameworks. (Might also be a good place to put any caveats about them, given we've run into four issues with modified Mocha behavior recently.) But it should also list how using the integration differs from just setting it up manually, if setting it up manually is possible.

• We get occasional questions about use with ES6; the docs currently mention that --compilers can be used for Coffeescript and don't elaborate on anything else in that regard.

I just now discovered that we... pass on --es_staging and --harmony* flags to Node? And some people even say they are no longer needed in current Node versions (but maybe I misunderstood for which features...). Yet I've seen so much discussion of issues surrounding Babel, even had to learn how to set it up myself to triage some of them (and definitely got errors before I added ES6 configuration to Babel), and there have been questions like the one linked in that bullet point about ES6 features not working. Should we document that people should try the --es_staging/--harmony* flags if they get errors about ES6 keywords, and only if that doesn't work try a transpiler with --compilers and whatever else is needed to configure them?

[ScottFreeCode]

globals/checkLeaks are underdocumented. There's all sorts of fancy stuff being done to test them in Mocha's own test suite that I don't understand from the description on Mochajs.org. For that matter, I suspect my problems getting checkLeaks to actually handle leaks properly might be due to incorrect usage. See also #2279.

[boneskull]

I'm a bit conflicted versus what belongs on the site and what belongs in README.md. Generally, if there's enough stuff to be documented, I'll see projects delegate to the site instead. A counterexample is browserify.

Then again, I'm unclear if @dasilvacontin means README.md as in README.md. If not, perhaps it behooves us to move this issue into mochajs/mochajs.github.io.

[dasilvacontin]

I meant README.md, but usually these things I left here were for links. Having a few sections with links in the README. Links to Wiki pages, or blog posts, whatever.

One more question often asked: How does mocha 'parse' the spec files?

[STRAYKR]

As a newbie, I was thrown off by the home page "Getting Started" example where it states "Back in the terminal:" and magically shows the output without showing how to run the tests. I had to go elsewhere to figure out the command ($ npm test) and how to set up package.json to alias the keyword "test" to point to the test dir.

I'm happy to create a pull request for this, but don't think the home page is under git control? If this is indeed stated somewhere in the wiki I couldn't find it. Can I assist in updating the docs somehow?

Something along the lines of:

Install Mocha

npm install mocha chai --save-dev

Notice that this is not installed globally. This allows for multiple projects with different versions of mocha to run side by side.

Create a test directory

~/projects/my-project $ mkdir test

Create a test file

cd test
~/projects/my-project/test $ touch test.js

Add an example test to test.js:

var assert = require('assert');
describe('Array', function() {
describe('#indexOf()', function() {
it('should return -1 when the value is not present', function() {
assert.equal(-1, [1,2,3].indexOf(4));
});
});
});

Update package.json

"scripts": {
"test": "./node_modules/mocha/bin/mocha ./test/"
}

With the above, you can now type 'npm test' to run your tests:

Run your tests

~/projects/my-project $ npm test

my-project@1.0.0 test /home/username/projects/my-project
./node_modules/mocha/bin/mocha ./test/

Array
#indexOf()
✓ should return -1 when the value is not present

1 passing (8ms)

[ScottFreeCode]

@TimHandy Sorry, I meant to reply to this before and it slipped through my to-do list. The code for mochajs.org should be in mochajs.github.io if I'm not mistaken. We also just got an issue there about the same point: mochajs/old-mochajs-site#57

[bdharris08]

@ScottFreeCode @TimHandy I submitted a PR - let me know what you think. mochajs/old-mochajs-site#58

[ScottFreeCode]

Do we have an issue equivalent to this one for documentation on the mochajs.org site? Most of my points are more appropriate there.

Here's another one: let's clarify the relationship between Mocha's --require, Node's require and Node's --require.

[boneskull]

@ScottFreeCode that makes me think there may be a use case for using both node's --require and mocha's --require. the former would be useful if you wanted to monkeypatch the CLI's behavior...

[boneskull]

otherwise, improving documentation on github, mochajs.org, and between the two is an ongoing (though slow) effort. the wiki needs to be audited for misinformation as well