livedoc-mocha0.3.4 • Public • Published
LiveDoc-mocha is a library for adding behavior using a language called Gherkin to the mocha testing library. The Gherkin syntax uses a combination of keywords and natural language. The specifications are written in plain english and are meant to be read by anyone on your team and used to aid in improving collaboration, communication and trust within the team. These specifications also help to reduce ambiguity, confusion about what needs to be built, the rules and importantly why its being built. This is the first step to the concept of Living Documentation.
NB: If you are viewing this from npmjs.com, links and images may be broken. Please visit the project site to view this document.
So what does this look like?
If we take the following feature which describes an account holder withdrawing money from an ATM. The format is the same as you might use in Cucumber.js, Cucumber, SpecFlow etc.
Feature: Account Holder withdraws cashAccount Holders should be able to withdraw cash at any of thecompanies ATMs.Rules:* Account Holders should have a valid keycard* Have sufficient available funds* The ATM has the necessary fundsScenario: Account has sufficient fundsGiven the account holders account has the following:| account | 12345 || balance | 100 || status | valid |And the machine contains 1000 dollarsWhen the Account Holder requests 20 dollarsThen the ATM should dispense 20 dollarsAnd the account balance should be 80 dollars
When run with livedoc-mocha will produce the following output:
Converting the original Gherkin to livedoc-mocha would looks like this:
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 library builds off the mocha.js library as a custom ui. To setup, follow these steps.
npm install --save-dev livedoc-mocha
To get the latest code and bug fixes, you can install the current beta. You can find details of the releases on the releases tab.
npm install --save-dev livedoc-mocha@beta
npm install mocha --save-dev
Once you have mocha 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:
mocha --ui livedoc-mocha --recursive path-to-my-tests/
For more details configuring mocha see the official mocha.js site.
If you are using typescript and the keywords are not being recognized add the following import statement to your test file.
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.
For full details of what's supported see the API reference
Also for a brief tutorial on how to write Gherkin specs using livedoc-mocha see the tutorial.
Release notes can be found here
livedoc-mocha supports the following command line options. These are useful when wanting to filter the features/scenarios that you want to run:
--ld-include: Used to only include features/scenarios that have been marked with the tags provided. Example use would be to only run what's been tagged with @integration.
--ld-include "_tag_ _tag_ _tag_"
--ld-exclude: Used to exclude features/scenarios that have been marked with the tags provided. Example use would be run everything except those tagged with @integration.
--ld-exclude "_tag_ _tag_ _tag_"
- --showFilterConflicts: When used will display conflicted filter matches as pending rather than not showing them at all.
ld-exclude switches can be used together to both include and exclude features/scenarios. When a conflict occurs by default the exclude will take precedence. However, there may be times when you want to know what the conflicts were. In that case using the
--showFilterConflicts will show the otherwise excluded scenarios but mark them as pending, so they are still not executed.
For more details on tags and tagging, refer to the Tags documentation in teh API reference.
Why another library?
mocha-cakes-2: A simple library that provides Gherkin aliases for the default mocha syntax. This library unlike Cucumber.js doesn't use a separate file and keeps the spec description with its implementation, in the same way LiveDoc-mocha does.
There are others too, however they typically fall into the two categories above, either separating the spec from the implementation or combining both.
There are pros and cons to both approaches, however LiveDoc-mocha went with the combining spec and implementation as the additional separation can be hard to maintain. However, if having separate files is your preferred style, then you should consider using Cucumber.js for your projects.
While mocha-cakes-2 provides a great starting point, its feature list was limited to simple aliasing. LiveDoc-mocha tries to deliver as much of the full spec as possible. The addition of more advanced features such as Tables, Values, docStrings and Backgrounds brings the experience much closer to the full Gherkin experience without the context switch you can experience with libraries like Cucumber.js.