User:DKinzler (WMF)/PhpUnit2Mocha

Test File Structure: describe and it
Actual code goes into a callback function that gets passed to a call it. All  calls are placed in a callback passed to. A test file contains one top level call to. The describe callback should contain no code except calls to  and to nested , setup code goes into   and  , see below. The only exception is

It may help to think of  and   and their callbacks as structural elements rather than function calls. The  and   functions generated the test definitions, they do not run them. Their execution time is before any of the actual test code runs, similar to how data providers in phpunit run before any test code.

Setup code that should run once before all tests in a file (like  in phpunit) gets placed in a callback passed to , setup code that should run before each test (like   in phpunit) goes into a callback passed to. and  apply to a   block.

The first parameter of  and   are human readable strings that should form a sentence when read together. For instance, if  contains a test in , then the full name of the test is read as "A car can go backwards", and that should be what the test asserts.

TBD

 * Fixtures
 * Promise.all for setup (and declaring things)
 * Chaining / variable passing
 * Data providers
 * Users, accounts, sessions
 * Misc utilities (title!)

Callbacks and Closures: function and arrow
Callbacks can be defined using either the old school  keyword creating an anonymous function, or the new arrow syntax. They are equivalent except for the meaning  within the code: the arrow syntax creates a closure that inherits any variables from the lexical scope it was created in, including the  reference. inside an function however, the meaning of  is determined by the caller.

While the arrow syntax is generally preferable, and more intuitive to developers used to PHP since they behave more like closures in PHP, it may be problematic for use in Mocha. Specifically, access to the Mocha environment itself is provided to the callback function. There isn't a good way to access from an arrow-style closure. Access to the Mocha environment may be needed for instance to set the timeout for tests.

Asynchronous I/O: await and async
In JavaScript, I/O operations are inherently asynchronous. This means that in tests against an API, all calls to that API are going to be asynchronous. The asynchronous nature of code in JavaScript is contagious: the only way to block and wait for a response is to prefix the call with the  keyword, but this is only allowed if the calling function is itself declared to by asynchronous, using the   keyword.

In effect, this means that all callbacks that contain test code for the API need to be declared, and all calls to any function that calls the API,directly or indirectly, needs to be prefixed with. There is alternative (older) style of handling asynchronous calls that is based on "thenable" promise objects, but this is discouraged for readability.

Forgetting the  prefix may cause confusing errors - the function will still be called, but the return value will be a Promise object, which will not contain the members that the actual return value is expected to have.

Local Variables: let and const
All local variables should be declared using either  or. Use  if the variable is not going to be re-assigned. The declaration of the variable name is valid inside the lexical scope (block) that contains the declaration, from the point of the declaration onward. Avoid using the old declaration style using.