Testing Reference Documentation

[odoe]

Type: doc

Description:

This adds testing documentation. As per #321 this pulls information from various sources. I am still cleaning it up, but wanted to get the PR in progress now for review. I'll continue to update.

I'm not quite sure how much info to put in to Basic Usage balanced with Supplemental and any overlapping content of the two.

The following sections are currently TODO

• Mocking
• Functional Tests

Resolves #321

[jsf-clabot]

All committers have signed the CLA.

[odoe]

Is sinon the recommended mocking method in dojo apps? I think historically, it has been, but wanted to make sure.

[sbinge]

Hi @odoe, thanks for tackling this reference guide!

A few notes & answers to your questions:

• We're looking to keep this guide focussed primarily on Dojo's testing harness/how to test Dojo apps and less so on use of external libraries. The harness should be the highest priority topic we discuss, with less emphasis on other libraries (even Intern could be considered an implementation detail). Effectively the order of the bullet points in Reference guide: Testing Dojo Applications #321 is the priority we should look to discuss topics in.

• In terms of mocking: following on from the above point, I think what you've added so far is on the right track - discussing the concepts in context of testing Dojo apps, while keeping references to external tools/libraries light. Certainly no detailed usage descriptions for external libraries, as these can change independently of what the Dojo project can control.

• For the split between basic usage and supplemental: basic usage is intended as complete working copy/pasteable examples of the main features a user will typically use when developing a Dojo application, with one or two sentences providing some extra context alongside the code snippets. Users can reference basic usage when they're looking to quickly ramp up a project - they know what they need to do, but want to shortcut it (e.g. copying import statements). It's almost a cookbook for the most-used features covered by the reference guide. A good rule of thumb is anything where users can choose alternative ways of doing things, or where they could use more detailed options to customize a feature, belongs in supplemental.

• Related to complete working copy/pasteable examples - this should also apply to snippets in supplemental (with few exceptions). Ideally the code examples include imports and full class/function scope, so readers can copy the samples and expect them to just work in their own applications.

• These new reference guides are intending to replace most of the detailed usage information currently available in the framework's READMEs. Rather than linking out to a README, we should consider moving relevant content into the reference guide with the expectation that we'll remove it from the README, replacing it with a link to the updated topic in the reference guide.

Great progress so far!

[agubler]

Hey @odoe do you have any more clean up left on this?

[agubler]

@odoe also could you run prettier on your changes? It should have ran as a pre-commit hook, not sure why it didn't but you can run it manually with npm run prettier

[odoe]

hi @agubler I think so. I moved some of the testing services down in the doc, reran prettier on everything.

[sbinge]

Thanks for the guide @odoe!

Also just a heads up in case you notice further changes made to it once it's merged - there are new APIs coming in Dojo v6 around functional widgets and associated middleware, including a new test harness to work with them. The class-based widgets and current test harness are not going anywhere, so everything currently here is still valid - we'll just be adding info around the functional APIs into this guide for the v6 launch.