Deity is a property generating tool for use when writing tests. It works well with tools like mocha.
You can read my introductory article on Deity here: Introducing Deity.
Given a string specifying a generator and arguments, Deity will call a given function a number of times with data generated from the specified generator.
You can give it any number of generator strings:
It also supports plugins, for example the randomuser.me plugin:
You can play with different generator strings on the Deity website and read the API documentation below.
deity( ...generatorStrings [ , options ] , callback )
The first argument,
generatorString, is a string containing the name of the
generator to use (for example, "string" or "number"), followed by some
arguments to give to the generator, all separated by colons. This argument can
be repeated as many times as you want.
The next argument is optional, and is an object where you can specify a number of options to override the defaults with, such as the number of time to call the callback.
The final argument should be the testing function to be called with the generated data. If you specify multiple generator strings, each one will be called as a separate argument of the function.
The Deity function returns a promise which is resolved or rejected depending on whether any errors are thrown in the callback function.
Usage with mocha
deity() function returns a promise which is either resolved or
rejected with any errors thrown inside the callback. To use Deity with mocha,
simply return the promise:
Note that in some cases when both the generator and testing function are synchronous, you don't need to return the promise, because the errors will be thrown normally.
Types of generators
The string generator generates strings of length n where n is a random number between two specified numbers.
string:5-10, for example, will generate strings of random length between 5
and 10 characters.
The letters the string is generated from is by default the capital letters A-Z,
but this can be configured using the
letters option (just specify a string of
characters to get the characters from).
If not specified, the default length of the string is 10-20.
This generator generates numbers within a given range of numbers at, if specified, a given precision.
number:3.1-4.7will generate random numbers between 3.1 and 4.7.
number:0-10:0.1will generate random numbers between 0 and 10, rounded to one decimal place.
number:0-1000:10will generate random numbers between 0 and 1000, rounded to the nearest ten.
The precision is optional: if not specified, the number will not be rounded (and as such, is extremely unlikely to be an integer). The range is also optional and defaults to "0-1".
The int generator is very similar to the number generator, but only generates whole numbers.
The range again is optional, and defaults to "0-10".
The char generator generates characters in a given range with a default of "A-Z".
charwill generate random characters
char:A-Mwill generate random characters in the first half of the alphabet.
The boolean generator generates true or false values with an optional bias. The bias should be a number between 0 and 1. The closer the number to 1, the more likely it is that "true" will be generated.
If the bias isn't specified, it will return true 50% of the time, and false the remaining 50% of the time.
To explain the oneOf generator and a few of the generators below, we introduce the concept of subgenerators. A subgenerator is a generator specified in brackets given as an argument to another generator.
The oneOf generator takes a number of generators, and picks one of them randomly to generate a value from. For example, take the following generator:
In that example, the
value variable will equal either:
- An integer between 10 and 20
- A character
- Or a boolean with a 20% chance of being true
This generator is similar to the oneOf generator, but instead of picking one of the generators, it uses all of them to generate an array where the first element will be a value generated by the first generator, the second element will be a value generated by the second generator, and so on.
value in that case could be
[15, 'F', false].
This generator generates the result of a given subgenerator called n times, concatenated together as a string.
The literal generator is mostly used internally. It takes a literal value and returns that value every time.
literal:"test"will generate "test" repeatedly.
literal:4will generate "4" repeatedly.
Internally, it uses the JSON parser to turn the value into an object, so you could specify more complicated values like arrays and objects.
The entry generator uses a given array or object to generate random values from the array or object. As the generator string is a string, the collection is specified in the options:
The generator also has an argument to specify the name of the option to use, but there aren't many cases you'd have to use it in:
A few generators have short forms you can use:
Will expand out to
"literal string values"
Will expand out to
literal:"literal string values".
Number and character ranges
You can specify number and character generators without the
A-Zwill expand out to
3.5-10will expand out to
Plugins and custom generators
Deity is easily extensible using plugins, and as they are ES6 generators, it is pretty simple to write your own.
Loading a plugin
If you have a plugin you want to load, or you found a plugin on npm by
searching "deity-plugin", you can use the
deity.extend() function to load it
into Deity. Take the following example:
var deity = ;var randomuser = ;deity;;
You can also change the name you want the generator to be added as:
There is only one plugin available right now:
Writing a plugin
You can read how to create your own plugin in this article: (coming soon). They're just ES6 generators, though:
You can install Deity from npm:
$ npm install --save-dev deity
Released under the MIT license.