You may not want to check the trivial case in random test. As we have seen, we can ignore the trivial case using the guard condition. However, on the other hand, we can watch how many trivial cases are appeared in random test.

ast_sort_triv =
  RushCheck::Assertion.new(Integer, Integer) do |x, y|
    RushCheck::guard { x <= y }
    ([x, y].sort == [x, y]).trivial{ x == y }
  end

irb> ast_sort_triv.check
OK, passed 100 tests(14%, trivial).
true

Here, we have 14% (i.e. 14 times) trivial (x == y) cases in the test.

In addition, we can give another names to watching statistics.

ast_sort_classify =
  RushCheck::Assertion.new(Integer, Integer) do |x, y|
    RushCheck::guard { x <= y }
    test = ([x, y].sort == [x, y])
    test.classify('same'){ x == y }.
      classify('bit diff'){ (x - y).abs == 1 }
  end

irb> ast_sort_classify.check
OK, passed 100 tests.
18%, same.
11%, bit diff.
true
irb>

Sometimes, we want to check special characters, for example the backslash ’\’ or unprinted characters ‘ESC’, ‘NUL’ and so on. SpecialString is a subclass of String which is defined in ‘rushcheck/string’. This library is already required in ‘rushcheck/rushcheck’ and don’t need to require again.

The output of random generator of SpecialString has different distribution of its of String. At String, the distribution of characters are normalized. On the other hand, the distribution in SpecialString is weighted and the generator provides special characters more often than alphabets. In detail, the distribution is as follows:

Using SpecialString in assertions, it is more likely to find the counter example. The following example is the famous bug which is called ‘malformed format bug’.

malformed_format_string =
  RushCheck::Assertion.new(String) { |s| sprintf(s); true }

malformed_format_string2 =
  RushCheck::Assertion.new(SpecialString) { |s| sprintf(s); true }

irb> malformed_format_string.check
Falsifiable, after 86 tests:
Unexpected exception: #<ArgumentError: malformed format string - %&>
    ... snip error traces ...
["\n&'e!]hr(%&\031Vi\003 }ss"]
false
irb> malformed_format_string2.check
Falsifiable, after 15 tests:
Unexpected exception: #<ArgumentError: malformed format string>
["%\037-R"]
false

In these results, we can see RushCheck find the counter example after 86 tests with String, on the other hand, find it quickly after 15 tests with SpecialString.

It is easy to change the distribution in SpecialString. You can define your subclass of SpecialString as follows:

class YourSpecialString < SpecialString
  @@frequency = { 'alphabet' => 1,
                  'control'  => 0,
                  'number'   => 0,
                  'special'  => 9 }
end

The meaning of randomness for Array must be changed in testing codes. Sometimes you needs a random array of Integer, and another a random array of String. So what is random array?

RushCheck provides an abstract class RandomArray for abstract random generator. Programmer have to write a subclass of RandomArray as follows:

# for random array of integers
class MyRandomArray < RandomArray; end
MyRandomArray.set_pattern(Integer) {|ary, i| Integer }

The class method set_pattern takes a variable and a block. Because array is inductive structure, it can be defined by the basecase and the inductive step.

For example, let’s consider a random array in the following pattern [Integer, String, Integer, String, ...] where it has a random Integer at the odd index and a random String at the even index. Then we can write a random array with this pattern:

MyRandomArray.set_pattern(Integer) do |ary, i|
  if i % 2 == 0
  then Integer
  else String
  end
end

• the first component is Integer
• if the i-th component is positive integer
  • then (i+1)-th component is String
  • otherwise the (i+1)-th component is Integer

MyRandomArray.set_pattern(Integer) do |ary, i|
  if ary[i].kind_of?(Integer) && ary[i] >= 0
  then String
  else Integer
  end
end

In this way, we can define any random array with any pattern.

Hash is also primitive and not so clear what is a random hash, like array. RushCheck provides an abstract random generator RandomHash, and programmer can write a subclass of RandomHash.

class MyRandomHash < RandomHash; end
pat = { 'key1' => Integer, 'key2' => String }
MyRandomHash.set_pattern(pat)

In this example, we can get a random Hash with two keys (‘key1’ and ‘key2’). Here the keys are String, but we can give any object as usual in Hash. Is it clear to define random hash? I think so. (If not it is clear, then the interface may be changed in future)

It is not difficult to create a random Proc object. As we saw in the previous sections, we have to write a subclass of RandomProc.

class MyRandomProc < RandomProc; end
MyRandomProc.set_pattern([Integer], [Integer])

Here, we define a random procedure which takes an integer and returns an integer also. In general, Ruby’s function and method can be regarded as a relation. (not a function in mathematics!) Therefore I think random procedures can be generated by a pair of inputs and outputs.

Let’s consider a simple example. In general, any functions f, g, and h should satisfy the associativity property:

for all x, f(g(h(x)) === (f . g)(h (x)) where f . g is a composition of functions in mathematical way

class Proc
  # application
  def **(other)
    Proc.new do |*args|
      res = other.call(*args)
      call(*res)
    end
  end
end

class MyRandomProc < RandomProc; end

def associativity_integer
  MyRandomProc.set_pattern([Integer], [Integer])
  RushCheck::Assertion.new(MyRandomProc, MyRandomProc,
                           MyRandomProc, Integer) do
    |f, g, h, x|
    (f ** (g ** h)).call(x) == ((f ** g) ** h).call(x)
  end.check
end

P.S. The arbitrary method is used to create a random object for test instance. Then you may wonder what is the coarbitrary method? The coarbitrary method is used to generate a random procedure (lambda), which is one of central idea in QuickCheck.

One simple random generator for Candy:

class Candy
  extend Arbitrary

  def self.arbitrary
    RushCheck::Gen.create(String, Integer) do |name, price|
      RushCheck::guard { price >= 0 }
      new(name, price)
    end
  end
end

Gen.create takes an array of Gen object (here, [Integer.arbitrary, String.arbitrary]) and a block. The block takes variables which is corresponded to the array, as Assertion.new. If guard is failed, then RushCheck retry to create another random instance.

Note that we can use a trick instead of the guard property.

  price = - price if price < 0   # g.guard { price >= 0 }

class Candy
  extend RushCheck::Arbitrary

  def self.arbitrary
    String.arbitrary.bind do |name|
      Integer.arbitrary.bind do |price|
        price = - price if price < 0   # trick as I described above
        RushCheck::Gen.unit(new(name, price))
      end
    end
  end
end

Puzzled? OK, they can be readed as follows:

• take a random (arbitrary) string and call it ‘name’
  • take a random integer and call it ‘price’
    • return a Gen object which has a new Candy(name, price)

In general, the class method arbitrary should return a Gen object. Check also gen.rb in RushCheck. There are several combinators to create random generators.

There are several way to implement random generators. The next example is to use Gen.new without bind and unit.

class Candy
  extend RushCheck::Arbitrary

  def self.arbitrary
    RushCheck::Gen.new do |n, r|
      r2 = r
      name, price = [String, Integer].map do |c|
        r1, r2 = r2.split
        c.arbitrary.value(n. r1)
      end
    price = - price if price < 0 # trick
      new(name, price)
    end
  end
end

This pattern is useful if your class has many valiables for initialize. Because binding patterns needs much depth of method call chains, it may be failed. This technique is used to avoid the stack overflow. This is one difference between Haskell and Ruby.

• self.arbitrary returns a new Gen object.
  • let n be an integer and r be a random generator.
  • let r2 equal r
  • name and price are both random objects where
    • get new two random generator r1 and r2 from old r2
    • assign a random value by generating ‘arbitrary.value(n, r1)’
      • and discard the random generator r1
      • ...

Note that we need new random generator for each random object. Here we create new random generator by spliting. If you use same random generator for generating different objects, then the distribution of objects are same (not generated randomly).

Because sometimes the initialize of YourClass is complecated, then the random generator self.arbitrary turns to be complicated also.

In next sections, I will introduce several generators in gen.rb. They may be useful to create your own random genrator. See also rdoc of Gen.

To help defining random objects in your class, there are several functions in Gen class.

Gen.choose(0, 10) # a generator of Integer in (0..10)

# return a random integer or a random string (by
# choosing randomly) Integer:30% String: 70%

Gen.frequency([[3, Integer.arbitrary], [7, String.arbitrary]])

class Candy
  extend RushCheck::Arbitrary

  def self.arbitrary
    RushCheck::Gen.lift_array([Integer, String]) do |c|
      c.arbitrary
    end.bind do |args|
      new(*args)
    end
  end
end

Gen.oneof([Integer.arbitrary, String.arbitrary])
  # return a random integer or a random string (by choosing
  # randomly)

Gen.vector(Integer, 3) # => Gen [Integer, Integer, Integer]