README.textile in rantly-0.3.1 vs README.textile in rantly-0.3.2
- old
+ new
@@ -1,5 +1,23 @@
+!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 Rant to generate random test data, and use its Test::Unit extension for property-based testing.
Rant is basically a recursive descent interpreter, each of its method returns a random value of some type (string, integer, float, etc.).
@@ -17,11 +35,11 @@
> 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]
+=> [-1843396915550491870, -1683855015308353854, -2291347782549033959, -951461511269053584, 483265231542292652]
</code></pre>
h1. Data Generation
h2. Getting Random Data Values
@@ -89,11 +107,11 @@
random positive or negative integer. Fixnum only.
Rantly#range(lo,hi)
random integer between lo and hi.
Rantly#float
random float
-Rantly#bool
+Rantly#boolean
true or false
Rantly#literal(value)
No-op. returns value.
Rantly#choose(*vals)
Pick one value from among vals.
@@ -250,43 +268,98 @@
Rantly::TooManyTries: Exceed gen limit 60: 60 failed guards)
</code></pre>
h1. Property Testing
-Rantly extends Test::Unit for property testing. The extension is in its own module. So you need to require it.
+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:
<pre><code>
-require 'rant/check'
+require 'rantly/testunit_extensions' # for 'test/unit'
+require 'rantly/minitest_extensions' # for 'minitest'
+require 'rantly/rspec_extensions' # for RSpec
</code></pre>
-It defines,
+They define:
<pre><code>
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'.
</code></pre>
-It's like this, using the gem 'shoulda'
+Property assertions within Test::Unit could be done like this,
<pre><code>
# checks that integer only generates fixnum.
-should "generate Fixnum only" do
- property_of { integer }.check { |i| assert i.is_a?(Integer) }
+property_of {
+ integer
+}.check { |i|
+ assert(i.is_a?(Integer), "integer property did not return Integer type")
+}
+</code></pre>
+
+Property assertions within Minitest could be done like this,
+
+<pre><code>
+# checks that integer only generates fixnum.
+property_of {
+ integer
+}.check { |i|
+ assert_kind_of Integer, i, "integer property did not return Integer type"
+}
+</code></pre>
+
+Property assertions within RSpec could be done like this,
+
+<pre><code>
+# 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
</code></pre>
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,
<pre><code>
-should "generate right sized array" do
- property_of {
- len = integer
- [len,array(len){integer}]
- }.check { |(len,arr)|
- assert_equal len, arr.length
- }
-end
+property_of {
+ len = integer
+ [len,array(len){integer}]
+}.check { |(len,arr)|
+ assert_equal len, arr.length
+}
</code></pre>
+
+If you wish to have quiet output from Rantly, set environmental variable:
+<pre><code>
+RANTLY_VERBOSE=0 # silent
+RANTLY_VERBOSE=1 # verbose and default if env is not set
+</code></pre>
+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 <code>Integer</code>, <code>String</code>, <code>Array</code>, and <code>Hash</code>.
+
+For example a <code>String</code> is shrinkable until it is empty (e.g. <code>""</code>),
+
+<pre><code>
+"foo".shrink # => "fo"
+"foo".shrink.shrink # => "f"
+"foo".shrink.shrink.shrink # => ""
+"".shrinkable? # => false
+</code></pre>
+
+Shrinking allows <code>Property#check</code> to find the minimum value that still fails the condition.
+
+Enable shrinking with
+
+<pre><code>
+require 'rantly/shrinks'
+</code></pre>
+
That's about it. Enjoy :)
h1. Copyright