BDD extensions for Mocha that support LiveDoc reporting.
npm install livedoc-mocha!logo
Gherkin
Feature: Beautiful Tea Shipping Costs
* Australian customers pay GST
* Overseas customers don’t pay GST
* Australian customers get free shipping for orders $100 and above
* Overseas customers all pay the same shipping rate regardless of order size
Background:
Given my background test
Scenario Outline: Calculate GST status and shipping rate
Given the customer is from
When the customer’s order totals
Then the customer pays GST
And they are charged the shipping rate
Examples:
| Customer’s Country | GST Amount | Order Total | Shipping Rate |
| Australia | 9.999 | 99.99 | Standard Domestic |
| Australia | 10.00 | 100.00 | Free |
| New Zealand | 0 | 99.99 | Standard International |
| New Zealand | 0 | 100.00 | Standard International |
| Zimbabwe | 0 | 100.00 | Standard International |
`
> The Background here is for illustration purposes, to demonstrate that Backgrounds are also supported.
When run with livedoc-mocha it will produce the following output, which looks very similar to the original Gherkin but with each of the examples being run:
!Mocha Test Result
\* using the livedoc-spec reporter
Converting the original Gherkin to livedoc-mocha, is straightforward as all the Gherkin features are fully supported. The final code looks like this:
`ts
feature(Beautiful Tea Shipping Costs
, () => {
background(, () => {
given(my background test, () => {
});
});
scenarioOutline(Calculate GST status and shipping rate
, () => {
const cart = new ShoppingCart();
given("the customer is from ", () => {
cart.country = scenarioOutlineContext.example.CustomersCountry;
});
when("the customer’s order totals ", () => {
const item = new CartItem();
item.quantity = 1;
item.price = scenarioOutlineContext.example.OrderTotal;
item.product = "tea";
cart.items.push(item);
cart.calculateInvoice();
});
then("the customer pays GST", () => {
cart.gst.should.be.equal(scenarioOutlineContext.example.GSTAmount);
});
and("they are charged the shipping rate", () => {
const rate = shippingRates[scenarioOutlineContext.example.ShippingRate.replace(" ", "")];
cart.shipping.should.be.equal(rate);
});
});
});
`
As can be seen by this simple example the actual test code is small and concise as much of the test setup was included as part of the test narrative. This in turn makes the test easier to understand and makes for excellent documentation.
This is just a small example of what can be done with LiveDoc-mocha. To understand more of what it can do, check out the API documentation.
The class used for this sample wasn't shown for brevity, however you can find the example source code here. This Spec is also part of the Tutorial documentation.
Installing
This library builds off the mocha.js library as a custom ui. To setup, follow these steps.
__Mocha__
Livedoc-mocha as the name suggests extends mocha which is a very popular javascript testing library. You will need to install mocha to use livedoc-mocha. You can install mocha with the following command:
` bat
npm install mocha --save-dev
`
__livedoc__
`bat
npm install --save-dev livedoc-mocha
`
To get the latest code and bug fixes, you can install the current beta, however this version may have bugs. You can find details of the releases on the releases tab.
`bat
npm install --save-dev livedoc-mocha@beta
`
__Configuring__
Once you have mocha & livedoc installed you need to configure mocha to run your tests and to use livedoc-mocha, a basic setup would be running this command from the command line:
`bat
mocha --ui livedoc-mocha --reporter livedoc-mocha/livedoc-spec --recursive path-to-my-tests/
`
The --reporter switch makes use of livedocs enhanced reporter specifically designed for Gherkin style Specs. While this is optional it is highly recommended that it be used. See the livedoc-spec reporter docs for more details.
For more details configuring mocha see the official mocha.js site.
__Typescript__
If you are using typescript and the keywords are not being recognized add the following import statement to the top of your test file.
`js
import "livedoc-mocha";
`
__Wallaby.js__
If you use wallaby.js you can configure livedoc-mocha by adding the following setup to your wallaby.js configuration file. If you already have a setup section then just include the two lines within your existing configuration file, otherwise copy this section to your file.
`js
setup: function (wallaby) {
require("livedoc-mocha");
wallaby.testFramework.ui('livedoc-mocha');
}
``