Need help with rantly?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

hayeah
209 Stars 19 Forks MIT License 111 Commits 1 Opened issues

Description

Ruby Imperative Random Data Generator and Quickcheck

Services available

!
?

Need anything else?

Contributors list

!https://travis-ci.org/hayeah/rantly.png?branch=master!:https://travis-ci.org/hayeah/rantly

h1. Repository move (Beginning 2015-07-07)

The official rantly repository has moved from "hayeah/rantly":https://github.com/hayeah/rantly to "abargnesi/rantly":https://github.com/abargnesi/rantly. The creator of rantly is "Howard Yeh":https://github.com/hayeah. "Anthony Bargnesi":https://github.com/abargnesi is the current maintainer.

New development will occur in "abargnesi/rantly":https://github.com/abargnesi/rantly.

The transition plan is as follows:

  • [x] Investigate and move open issues from "hayeah/rantly":https://github.com/hayeah/rantly to "abargnesi/rantly":https://github.com/abargnesi/rantly.
  • [x] Evaluate and likely merge pull requests into hayeah/rantly. Push these changes to "abargnesi/rantly":https://github.com/abargnesi/rantly.
  • [x] Move over any closed issues that have relevant discourse.
  • [ ] Fix open issues.
  • [x] Push new gem version after testing functionality.
  • [ ] Continue new development; Changes will be pushed back upstream to "hayeah/rantly":https://github.com/hayeah/rantly over the course of the next month.
  • [x] Added CHANGELOG markdown file. Includes what was added between 0.3.1 (2011-12-15) and 0.3.2 (2015-09-16).

h1. Imperative Random Data Generator and Quickcheck

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.

h1. Install


$ gem install rantly

$ 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]

h1. Data Generation

h2. Getting Random Data Values


Rantly#map(n,limit=10,&block)
  call the generator n times, and collect values
Rantly#each(n,limit=10,&block)
  call a random block n times
Rantly#value(limit=10,&block)
  call a random block once, and get its value.

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) { puts integer }
296971291
504994512
-402790444
113152364
502842783
=> nil

To get one value of random data,


> Rantly { integer }
=> 278101042

The optional argument @[email protected] 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; guard i > 0; i }
=> [511765059, 250554234, 305947804, 127809156, 285960387]

This always fails,


> Rantly(10) { guard integer.is_a?(Float) }
Rantly::TooManyTries: Exceed gen limit 100: 101 failed guards)

h2. Random Generating Methods

The API is similiar to QuickCheck, but not exactly the same. In particular @[email protected] picks a random element from an array, and @[email protected] picks a integer from an interval.

h3. Simple Randomness


Rantly#integer(n=nil)
  random positive or negative integer. Fixnum only.
Rantly#range(lo,hi)
  random integer between lo and hi.
Rantly#float
  random float
Rantly#boolean
  true or false
Rantly#literal(value)
  No-op. returns value.
Rantly#choose(*vals)
  Pick one value from among vals.

h3. Meta Randomness

A rant generator is just a mini interpreter. It's often useful to go meta,


Rantly#call(gen)
  If gen is a Symbol, just do a method call with send.
  If gen is an Array, the first element of the array is the method name, the rest are args.
  If gen is a Proc, instance_eval it with the generator.

> Rantly { call(:integer) }
=> -240998958

> Rantly { call([:range,0,10]) }
=> 2

> Rantly { call(Proc.new { [integer] })}
=> [522807620]

The @[email protected] method is useful to implement other abstractions (See next subsection).


Rantly#branch(*args)
  Pick a random arg among args, and Rantly#call it.

50-50 chance getting an integer or float,


> Rantly { branch :integer, :float }
=> 0.0489446702931332
> Rantly { branch :integer, :float }
=> 494934533

h3. Frequencies


Rantly#freq(*pairs)
  Takes a list of 2-tuples, the first of which is the weight, and the second a Rantly#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, @[email protected] 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, @[email protected] 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], [:integer 20] }

h3. Sized Structure

A Rantly generator keeps track of how large a datastructure it should generate with its @[email protected] attribute.


Rantly#size
 returns the current size
Rantly#sized(n,&block)
 sets the size for the duration of recursive call of block. Block is instance_eval with the generator.

Rantly provides two methods that depends on the size


Rantly#array(size=default_size,&block)
  returns a sized array consisted of elements by Rantly#calling random branches.
Rantly#string(char_class=:print)
  returns a sized random string, consisted of only chars from a char_class.
Rantly#dict(size=default_size,&block)
  returns a sized random hash. The generator block should generate tuples of keys and values (arrays that have two elements, the first one is used as key, and the second as value).

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!", "HojnxGDT3", "]a:L[B>bhb", "_Kl=&{tH^

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%-888111605212388599,
 "+SMn:r"=>-1159506450084197716,
 "^3gYfQ"=>-2154064981943219558,
 "= :/\\,"=>433790301059833691}

The @[email protected] 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: Exceed gen limit 60: 60 failed guards)

h1. Property Testing

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)
  The block is used to generate random data with a generator. The method returns a Rantly::Property instance, that has the method '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_of Integer, 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" do
   property_of {
     integer
   }.check { |i|
     expect(i).to be_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_equal len, arr.length
}

If you wish to have quiet output from Rantly, set environmental variable:


RANTLYVERBOSE=0 # silent
RANTLYVERBOSE=1 # verbose and default if env is not set
This will silence the puts, print, and pretty_print statements in property.rb.

h1. Shrinking

Shrinking reduces the value of common types to some terminal lower bound. These functions are added to the Ruby types Integer, String, Array, and Hash.

For example a String is shrinkable until it is empty (e.g. ""),


"foo".shrink               # => "fo"
"foo".shrink.shrink        # => "f"
"foo".shrink.shrink.shrink # => ""
"".shrinkable?             # => false

Shrinking allows Property#check to find the minimum value that still fails the condition.

Enable shrinking with


require 'rantly/shrinks'

That's about it. Enjoy :)

h1. Copyright

Copyright (c) 2009 Howard Yeh. See LICENSE for details.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.