- Notifications
You must be signed in to change notification settings - Fork21
Ruby Imperative Random Data Generator and Quickcheck
License
rantly-rb/rantly
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
You can use Rantly to generate random test data, and use its Test::Unit extension for property-based testing.
Rantly is basically a recursive descent interpreter, each of its method returns a random value of some type (string, integer, float, etc.).
Its implementation has no alien mathematics inside. Completely side-effect-free-free.
Rantly requires Ruby 3.2 or higher. To install Rantly add it to your Gemfile or run:
$geminstallrantly
You can try it in the console by running:
$irb -rrantly>Rantly{[integer,float]}# same as Rantly.value { integer }=>[20991307,0.025756845811823]>Rantly{[integer,float]}=>[-376856492,0.452245765751706]>Rantly(5){integer}# same as Rantly.map(5) { integer }=>[-1843396915550491870, -1683855015308353854, -2291347782549033959, -951461511269053584,483265231542292652]
Rantly#map(n,limit=10,&block)callthegeneratorntimes,andcollectvaluesRantly#each(n,limit=10,&block)callarandomblockntimesRantly#value(limit=10,&block)callarandomblockonce,andgetitsvalue.
To collect an array of random data,
# we want 5 random integers>Rantly(5){integer}=>[-380638946, -29645239,344840868,308052180, -154360970]
To iterate over random data,
>Rantly.each(5){putsinteger}296971291504994512-402790444113152364502842783=>nil
To get one value of random data,
>Rantly{integer}=>278101042
The optional argumentlimit is used with generator guard. By default, if you want to generate n items, the generator tries at most n * 10 times.
This almost always succeeds,
>Rantly(5){i=integer;guardi >0;i}=>[511765059,250554234,305947804,127809156,285960387]
This always fails,
>Rantly(10){guardinteger.is_a?(Float)}Rantly::TooManyTries:Exceedgenlimit100:101failedguards)
The API is similiar to QuickCheck, but not exactly the same. In particularchoose picks a random element from an array, andrange picks a integer from an interval.
Rantly#integer(n=nil)randompositiveornegativeinteger.Fixnumonly.Rantly#range(lo,hi)randomintegerbetweenloandhi.Rantly#floatrandomfloatRantly#booleantrueorfalseRantly#literal(value)No-op.returnsvalue.Rantly#choose(*vals)Pickonevaluefromamongvals.
A rant generator is just a mini interpreter. It's often useful to go meta,
Rantly#call(gen)IfgenisaSymbol,justdoamethodcallwithsend.IfgenisanArray,thefirstelementofthearrayisthemethodname,therestareargs.IfgenisaProc,instance_evalitwiththegenerator.
>Rantly{call(:integer)}=> -240998958
>Rantly{call([:range,0,10])}=>2
>Rantly{call(Proc.new{[integer]})}=>[522807620]
Thecall method is useful to implement other abstractions (See next subsection).
Rantly#branch(*args)Pickarandomargamongargs,andRantly#call it.
50-50 chance getting an integer or float,
>Rantly{branch:integer,:float}=>0.0489446702931332>Rantly{branch:integer,:float}=>494934533
Rantly#freq(*pairs)Takesalistof2-tuples,thefirstofwhichistheweight,andthesecondaRantly#callable value, and returns a random value picked from the pairs. Follows the distribution pattern specified by the weights.
Twice as likely to get a float than integer. Never gets a ranged integer.
>Rantly{freq[1,:integer],[2,:float],[0,:range,0,10]}
If the "pair" is not an array, but just a symbol,freq assumes that the weight is 1.
# 50-50 between integer and float>Rantly{freq:integer,:float}
If a "pair" is an Array, but the first element is not an Integer,freq assumes that it's a Rantly method-call with arguments, and the weight is one.
# 50-50 chance generating integer limited by 10, or by 20.>Rantly{freq[:integer,10],[:integer20]}
A Rantly generator keeps track of how large a datastructure it should generate with itssize attribute.
Rantly#sizereturnsthecurrentsizeRantly#sized(n,&block)setsthesizeforthedurationofrecursivecallofblock.Blockisinstance_evalwiththegenerator.
Rantly provides two methods that depends on the size
Rantly#array(size=default_size,&block)returnsasizedarrayconsistedofelementsbyRantly#calling random branches.Rantly#string(char_class=:print)returnsasizedrandomstring,consistedofonlycharsfromachar_class.Rantly#dict(size=default_size,&block)returnsasizedrandomhash.Thegeneratorblockshouldgeneratetuplesofkeysandvalues(arraysthathavetwoelements,thefirstoneisusedaskey,andthesecondasvalue).
The avaiable char classes for strings are:
:alnum:alpha:blank:cntrl:digit:graph:lower:print:punct:space:upper:xdigit:ascii
# sized 10 array of integers>Rantly{array(10){integer}}=>[417733046, -375385433,0.967812380000118,26478621,0.888588160450082,250944144,305584916, -151858342,0.308123867823313,0.316824642414253]
If you set the size once, it applies to all subsequent recursive structures. Here's a sized 10 array of sized 10 strings,
>Rantly{sized(10){array{string}}}=>["1c}C/,9I#}","hpA/UWPJ\\j","H'~ERtI`|]","%OUaW\\%uQZ","Z2QdY=G~G!","H<o|<FARGQ","g>ojnxGDT3","]a:L[B>bhb","_Kl=&{tH^<","ly]Yfb?`6c"]
Or a sized 10 array of sized 5 strings,
>Rantly{array(10){sized(5){string}}}=>["S\"jf ","d\\F-$","-_8pa","IN0iF","SxRV$",".{kQ7","6>;fo","}.D8)","P(tS'","y0v/v"]
Generate a hash that has 5 elements,
>Rantly{dict{[string,integer]}}{"bR\\qHn"=>247003509502595457,"-Mp '."=>653206579583741142,"gY%<SV"=>-888111605212388599,"+SMn:r"=>-1159506450084197716,"^3gYfQ"=>-2154064981943219558,"= :/\\,"=>433790301059833691}
Thedict generator retries if a key is duplicated. If it fails to generate a unique key after too many tries, it gives up by raising an error:
>Rantly{dict{["a",integer]}}Rantly::TooManyTries:Exceedgenlimit60:60failedguards)
Rantly extends Test::Unit and Minitest::Test (5.0)/Minitest::Unit::TestCase (< 5.0) for property testing. The extensions are in their own modules. So you need to require them explicitly:
require'rantly/testunit_extensions'# for 'test/unit'require'rantly/minitest_extensions'# for 'minitest'require'rantly/rspec_extensions'# for RSpec
They define:
Test::Unit::Assertions#property_of(&block)Theblockisusedtogeneraterandomdatawithagenerator.ThemethodreturnsaRantly::Propertyinstance,thathasthemethod'check'.
Property assertions within Test::Unit could be done like this,
# checks that integer only generates fixnum.property_of{integer}.check{ |i|assert(i.is_a?(Integer),"integer property did not return Integer type")}
Property assertions within Minitest could be done like this,
# checks that integer only generates fixnum.property_of{integer}.check{ |i|assert_kind_ofInteger,i,"integer property did not return Integer type"}
Property assertions within RSpec could be done like this,
# checks that integer only generates fixnum.it"integer property only returns Integer type"doproperty_of{integer}.check{ |i|expect(i).tobe_a(Integer)}end
The check block takes the generated data as its argument. One idiom I find useful is to include a parameter of the random data for the check argument. For example, if I want to check that Rantly#array generates the right sized array, I could say,
property_of{len=integer[len,array(len){integer}]}.check{ |(len,arr)|assert_equallen,arr.length}
To control the number of property tests to generate, you have three options. In order of precedence:
- Pass an integer argument to
check
property_of{integer}.check(9000){ |i|assert_kind_ofInteger,i}
- Set the
RANTLY_COUNTenvironment variable
RANTLY_COUNT=9000rubymy_property_test.rb
- If neither of the above are set, the default will be to run the
checkblock 100 times.
If you wish to have quiet output from Rantly, set environmental variable:
RANTLY_VERBOSE=0# silentRANTLY_VERBOSE=1# verbose and default if env is not set
This will silence the puts, print, and pretty_print statements in property.rb.
Shrinking reduces the value of common types to some terminal lower bound. These functions are added to the Ruby typesInteger,String,Array, andHash.
For example aString is shrinkable until it is empty (e.g.""),
"foo".shrinkable?# => true"foo".shrink# => "fo""fo".shrink# => "f""f".shrink# => """".shrinkable?# => false
Shrinking allowsProperty#check to find a reduced value that still fails the condition. The value is not truely minimal because:
- we do not perform a complete in-depth traversal of the failure tree
- we limit the search to a maximum 1024 shrinking operations
but is usually reduced enough to start debugging.
Enable shrinking with
require'rantly/shrinks'
UseTuple class if you want an array whose elements are individually shrinked, but are not removed. Example:
property_of{len=range(0,10)Tuple.new(array(len){integer})}.check{# .. property check here ..}
UseDeflating class if you want an array whose elements are individully shrinked whenever possible, and removed otherwise. Example:
property_of{len=range(0,10)Deflating.new(array(len){integer})}.check{# .. property check here ..}
Normal arrays or hashes are not shrinked.
Thanks toall contributors. 💘 New contributors are welcome! 😉
Logotype designed by:@Richardbmx
Code published under MIT License, Copyright (c) 2009 Howard Yeh. SeeLICENSE.
About
Ruby Imperative Random Data Generator and Quickcheck
Topics
Resources
License
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Packages0
Uh oh!
There was an error while loading.Please reload this page.