5 releases
0.2.0 | Feb 4, 2021 |
---|---|
0.1.21 | Dec 6, 2020 |
0.1.20 | Dec 6, 2020 |
0.1.19 | Nov 28, 2020 |
0.1.0 | Apr 26, 2020 |
#573 in Testing
37KB
513 lines
jtd-fuzz
jtd-fuzz
generates example data (aka "fuzz tests") from a JSON Typedef
schema.
echo '{ "elements": { "type": "string" }}' | jtd-fuzz -n 5
["_","/+Z`","8o~5[7A"]
[]
["@(;","*+!YVz"]
["u4sv>Sp","Uc","o`"]
["","G","*ZJsc","","","\"RT,","l>l"]
Installation
On macOS, you can install jtd-fuzz
via Homebrew:
brew install jsontypedef/jsontypedef/jtd-fuzz
For all other platforms, you can download and extract the binary yoursel from
the latest release. You can also install using cargo
by running:
cargo install jtd_fuzz
Usage
Basic Usage
To invoke jtd-fuzz
, you can either:
- Have it read from STDIN. This is the default behavior.
- Have it read from a file. To do this, pass a file name as the last argument
to
jtd-fuzz
.
jtd-fuzz
reads in a single JSON Typedef schema, and will output, by default,
an infinite stream of examples. For example, this will output an infinite
sequence of random JSON data:
echo '{}' | jtd-fuzz
If you'd like to have jtd-fuzz
output an exact number of results, use -n
:
echo '{}' | jtd-fuzz -n 5
Or, to have jtd-fuzz
read from a file:
echo '{ "type": "timestamp" }' > foo.jtd.json
jtd-fuzz -n 5 foo.jtd.json
Generating emails, names, etc. with fuzzHint
Oftentimes, it's useful for jtd-fuzz
to generate specific sorts of strings,
instead of the generic nonsense strings you get by default with {"type": "string"}
. You can customize jtd-fuzz
's output using the fuzzHint
metadata
property. For example, this schema:
{
"metadata": {
"fuzzHint": "en_us/internet/email"
},
"type": "string"
}
Would, if you put it in a file called example.jtd.json
, generate data like
this:
jtd-fuzz -n 5 example.jtd.json
"nerdman9@bergnaum.name"
"christopkulas@crooks.biz"
"ykozey5@wiza.org"
"rowenakunde@lang.com"
"udouglas01@carter.info"
fuzzHint
will only work on schemas of {"type": "string"}
. Here are some
commonly-used values for fuzzHint
:
en_us/company/company_name
generates strings likeHayes, Murray, and Kiehn
en_us/internet/email
generates strings likealainatorphy@johnson.com
en_us/names/full_name
generates strings likeAlexa Wisozk
A full list of possible values for fuzzHint
is available
here.
Advanced Usage: Providing a Seed
By default, jtd-fuzz
will generate different output every time:
echo '{}' | jtd-fuzz -n 1 ; echo '{}' | jtd-fuzz -n 1
{"[jD|6W":null}
null
If you'd like to get consistent output from jtd-fuzz
, or be able to reproduce
its output, you can use the -s
option to provide a seed to its internal
pseudo-random number generator. For the same seed and schema, jtd-fuzz
will
output the same data every time:
echo '{}' | jtd-fuzz -n 1 -s 8927 ; echo '{}' | jtd-fuzz -n 1 -s 8927
48
48
The -s
option takes an integer between 0 and 2^64 - 1.
Seeding jtd-fuzz
can be useful if you're using jtd-fuzz
to do automated
testing against a system. Your automated testing system can pass jtd-fuzz
a
randomly-generated seed, and if the automated tester finds a seed that reveals a
bug, it can output the seed it used. That way, developers can re-use that seed,
and try to reproduce the issue locally.
Note that jtd-fuzz
is only guaranteed to produce consistent output if you use
the same seed, schema, and version of jtd-fuzz
. Different versions on
jtd-fuzz
may output different results, even if you give them the same seed and
schema.
Security Considerations
Do not rely on jtd-fuzz
as a source of cryptographically secure randomness.
jtd-fuzz
is meant to be used as a generator of example data, such as for fuzz
testing applications. It is not meant to be used for cryptographic purposes.
Dependencies
~4–5.5MB
~90K SLoC