rantly 0.2.0 → 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- data/.travis.yml +16 -0
- data/CHANGELOG.md +94 -0
- data/Gemfile +11 -0
- data/LICENSE +3 -0
- data/README.md +417 -0
- data/Rakefile +13 -30
- data/VERSION.yml +4 -4
- data/lib/rantly/data.rb +1 -1
- data/lib/rantly/generator.rb +126 -112
- data/lib/rantly/minitest.rb +1 -0
- data/lib/rantly/minitest_extensions.rb +15 -0
- data/lib/rantly/property.rb +60 -29
- data/lib/rantly/rspec.rb +1 -0
- data/lib/rantly/rspec_extensions.rb +8 -0
- data/lib/rantly/shrinks.rb +192 -0
- data/lib/rantly/silly.rb +42 -42
- data/lib/rantly/spec.rb +4 -4
- data/lib/rantly/testunit_extensions.rb +8 -0
- data/lib/rantly.rb +10 -2
- data/rantly.gemspec +36 -49
- data/test/rantly_test.rb +103 -225
- data/test/shrinks_test.rb +104 -0
- data/test/test_helper.rb +12 -8
- metadata +50 -45
- data/.gitignore +0 -5
- data/README.textile +0 -296
data/README.textile
DELETED
@@ -1,296 +0,0 @@
|
|
1
|
-
h1. Imperative Random Data Generator and Quickcheck
|
2
|
-
|
3
|
-
You can use Rant to generate random test data, and use its Test::Unit extension for property-based testing.
|
4
|
-
|
5
|
-
Rant is basically a recursive descent interpreter, each of its method returns a random value of some type (string, integer, float, etc.).
|
6
|
-
|
7
|
-
Its implementation has no alien mathematics inside. Completely side-effect-free-free.
|
8
|
-
|
9
|
-
h1. Install
|
10
|
-
|
11
|
-
<pre><code>
|
12
|
-
$ gem install hayeah-rant --source http://gems.github.com
|
13
|
-
</code></pre>
|
14
|
-
|
15
|
-
<pre><code>
|
16
|
-
$ irb
|
17
|
-
> gem 'rant'
|
18
|
-
> require 'rant'
|
19
|
-
> Rant.gen.value { [integer,float] }
|
20
|
-
=> [20991307, 0.025756845811823]
|
21
|
-
> Rant.gen.value { [integer,float]}
|
22
|
-
=> [-376856492, 0.452245765751706]
|
23
|
-
</code></pre>
|
24
|
-
|
25
|
-
|
26
|
-
h1. Data Generation
|
27
|
-
|
28
|
-
You can create random generators from the Rant class. Rant.gen is just returns a class instance of Rant.
|
29
|
-
|
30
|
-
<pre><code>
|
31
|
-
> gen = Rant.new
|
32
|
-
> gen.value { [integer,float] }
|
33
|
-
=> [-163260081, 0.356075765934108]
|
34
|
-
</code></pre>
|
35
|
-
|
36
|
-
h2. Getting Random Data Values
|
37
|
-
|
38
|
-
<pre><code>
|
39
|
-
Rant#map(n,limit=10)
|
40
|
-
call the generator n times, and collect values
|
41
|
-
Rant#each(n,limit=10)
|
42
|
-
call a random block n times
|
43
|
-
Rant#value(limit=10)
|
44
|
-
call a random block once, and get its value.
|
45
|
-
</code></pre>
|
46
|
-
|
47
|
-
To collect an array of random data,
|
48
|
-
|
49
|
-
<pre><code>
|
50
|
-
# we want 5
|
51
|
-
> gen.map(5) { integer }
|
52
|
-
=> [-380638946, -29645239, 344840868, 308052180, -154360970]
|
53
|
-
</code></pre>
|
54
|
-
|
55
|
-
To iterate over random data,
|
56
|
-
|
57
|
-
<pre><code>
|
58
|
-
> gen.each(5) { puts integer }
|
59
|
-
296971291
|
60
|
-
504994512
|
61
|
-
-402790444
|
62
|
-
113152364
|
63
|
-
502842783
|
64
|
-
=> nil
|
65
|
-
</code></pre>
|
66
|
-
|
67
|
-
To get one value of random data,
|
68
|
-
|
69
|
-
<pre><code>
|
70
|
-
> gen.value { integer }
|
71
|
-
=> 278101042
|
72
|
-
</code></pre>
|
73
|
-
|
74
|
-
The optional argument @limit@ is used with generator guard. By default, if you want to generate n items, the generator tries at most n * 10 times.
|
75
|
-
|
76
|
-
This almost always succeeds,
|
77
|
-
|
78
|
-
<pre><code>
|
79
|
-
> gen.map(5) { i = integer; guard i > 0; i }
|
80
|
-
=> [511765059, 250554234, 305947804, 127809156, 285960387]
|
81
|
-
</code></pre>
|
82
|
-
|
83
|
-
This always fails,
|
84
|
-
|
85
|
-
<pre><code>
|
86
|
-
> gen.map(10) { guard integer.is_a?(Float) }
|
87
|
-
Rant::TooManyTries: Exceed gen limit 100: 101 failed guards)
|
88
|
-
</code></pre>
|
89
|
-
|
90
|
-
h2. Random Generating Methods
|
91
|
-
|
92
|
-
The API is similiar to QuickCheck, but not exactly the same. In particular @choose@ picks a random element from an array, and @range@ picks a integer from an interval.
|
93
|
-
|
94
|
-
h3. Simple Randomness
|
95
|
-
|
96
|
-
<pre><code>
|
97
|
-
Rant#integer(n=nil)
|
98
|
-
random positive or negative integer. Fixnum only.
|
99
|
-
Rant#range(lo,hi)
|
100
|
-
random integer between lo and hi.
|
101
|
-
Rant#float
|
102
|
-
random float
|
103
|
-
Rant#bool
|
104
|
-
true or false
|
105
|
-
Rant#literal(value)
|
106
|
-
No-op. returns value.
|
107
|
-
Rant#choose(*vals)
|
108
|
-
Pick one value from among vals.
|
109
|
-
</code></pre>
|
110
|
-
|
111
|
-
h3. Meta Randomness
|
112
|
-
|
113
|
-
A rant generator is just a mini interpreter. It's often useful to go meta,
|
114
|
-
|
115
|
-
<pre><code>
|
116
|
-
Rant#call(gen)
|
117
|
-
If gen is a Symbol, just do a method call with send.
|
118
|
-
If gen is an Array, the first element of the array is the method name, the rest are args.
|
119
|
-
If gen is a Proc, instance_eval it with the generator.
|
120
|
-
</code></pre>
|
121
|
-
|
122
|
-
<pre><code>
|
123
|
-
> gen.value { call(:integer) }
|
124
|
-
=> -240998958
|
125
|
-
</code></pre>
|
126
|
-
|
127
|
-
<pre><code>
|
128
|
-
> gen.value { call([:range,0,10]) }
|
129
|
-
=> 2
|
130
|
-
</code></pre>
|
131
|
-
|
132
|
-
<pre><code>
|
133
|
-
> gen.value { call(Proc.new { [integer] })}
|
134
|
-
=> [522807620]
|
135
|
-
</code></pre>
|
136
|
-
|
137
|
-
The @call@ method is useful to implement other abstractions (See next subsection).
|
138
|
-
|
139
|
-
<pre><code>
|
140
|
-
Rant#branch(*args)
|
141
|
-
Pick a random arg among args, and Rant#call it.
|
142
|
-
</code></pre>
|
143
|
-
|
144
|
-
50-50 chance getting an integer or float,
|
145
|
-
|
146
|
-
<pre><code>
|
147
|
-
> gen.value { branch :integer, :float }
|
148
|
-
=> 0.0489446702931332
|
149
|
-
> gen.value { branch :integer, :float }
|
150
|
-
=> 494934533
|
151
|
-
</code></pre>
|
152
|
-
|
153
|
-
|
154
|
-
h3. Frequencies
|
155
|
-
|
156
|
-
<pre><code>
|
157
|
-
Rant#freq(*pairs)
|
158
|
-
Takes a list of 2-tuples, the first of which is the weight, and the second a Rant#callable value, and returns a random value picked from the pairs. Follows the distribution pattern specified by the weights.
|
159
|
-
</code></pre>
|
160
|
-
|
161
|
-
Twice as likely to get a float than integer. Never gets a ranged integer.
|
162
|
-
|
163
|
-
<pre><code>
|
164
|
-
> gen.value { freq [1,:integer], [2,:float], [0,:range,0,10] }
|
165
|
-
</code></pre>
|
166
|
-
|
167
|
-
If the "pair" is not an array, but just a symbol, @freq@ assumes that the weight is 1.
|
168
|
-
|
169
|
-
<pre><code>
|
170
|
-
# 50-50 between integer and float
|
171
|
-
> gen.value { freq :integer, :float }
|
172
|
-
</code></pre>
|
173
|
-
|
174
|
-
If a "pair" is an Array, but the first element is not an Integer, @freq@ assumes that it's a Rant method-call with arguments, and the weight is one.
|
175
|
-
|
176
|
-
<pre><code>
|
177
|
-
# 50-50 chance generating integer limited by 10, or by 20.
|
178
|
-
> gen.value { freq [:integer,10], [:integer 20] }
|
179
|
-
</code></pre>
|
180
|
-
|
181
|
-
|
182
|
-
|
183
|
-
h3. Sized Structure
|
184
|
-
|
185
|
-
A Rant generator keeps track of how large a datastructure it should generate with its @size@ attribute.
|
186
|
-
|
187
|
-
<pre><code>
|
188
|
-
Rant#size
|
189
|
-
returns the current size
|
190
|
-
Rant#sized(n,&block)
|
191
|
-
sets the size for the duration of recursive call of block. Block is instance_eval with the generator.
|
192
|
-
</code></pre>
|
193
|
-
|
194
|
-
Rant provides two methods that depends on the size
|
195
|
-
|
196
|
-
<pre><code>
|
197
|
-
Rant#array(*branches)
|
198
|
-
returns a sized array consisted of elements by Rant#calling random branches.
|
199
|
-
Rant#string(char_class=:print)
|
200
|
-
returns a sized random string, consisted of only chars from a char_class.
|
201
|
-
</code></pre>
|
202
|
-
|
203
|
-
The avaiable char classes for strings are:
|
204
|
-
|
205
|
-
<pre><code>
|
206
|
-
:alnum
|
207
|
-
:alpha
|
208
|
-
:blank
|
209
|
-
:cntrl
|
210
|
-
:digit
|
211
|
-
:graph
|
212
|
-
:lower
|
213
|
-
:print
|
214
|
-
:punct
|
215
|
-
:space
|
216
|
-
:upper
|
217
|
-
:xdigit
|
218
|
-
:ascii
|
219
|
-
</code></pre>
|
220
|
-
|
221
|
-
<pre><code>
|
222
|
-
# sized 10 array of integer or float
|
223
|
-
> gen.value { sized(10) { array(:integer,:float)}}
|
224
|
-
=> [417733046, -375385433, 0.967812380000118, 26478621, 0.888588160450082, 250944144, 305584916, -151858342, 0.308123867823313, 0.316824642414253]
|
225
|
-
|
226
|
-
# fails if you forget to set the size.
|
227
|
-
> gen.value { array(:integer,:float)}
|
228
|
-
RuntimeError: size not set
|
229
|
-
|
230
|
-
</code></pre>
|
231
|
-
|
232
|
-
If you set the size once, it applies to all subsequent recursive structures. Here's a sized 10 array of sized 10 strings,
|
233
|
-
|
234
|
-
<pre><code>
|
235
|
-
> gen.value { sized(10) { array(:string)} }
|
236
|
-
=> ["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"]
|
237
|
-
</code></pre>
|
238
|
-
|
239
|
-
Or a sized 10 array of sized 5 strings,
|
240
|
-
|
241
|
-
<pre><code>
|
242
|
-
> gen.value { sized(10) { array Proc.new {sized(5) {string}}}}
|
243
|
-
=> ["S\"jf ", "d\\F-$", "-_8pa", "IN0iF", "SxRV$", ".{kQ7", "6>;fo", "}.D8)", "P(tS'", "y0v/v"]
|
244
|
-
</code></pre>
|
245
|
-
|
246
|
-
Rant#array actually just delegate to Rant#freq, so you can use freq pairs:
|
247
|
-
|
248
|
-
<pre><code>
|
249
|
-
> gen.value { sized(10) {array [1,:integer],[2,:float] }}
|
250
|
-
=> [0.983334733158678, -418176338, 0.976947175363592, 0.703390570421286, -478680395, 5483631, 0.966944106783513, 110469205, 0.540859146793544, 0.521813810037025]
|
251
|
-
</code></pre>
|
252
|
-
|
253
|
-
|
254
|
-
h1. Property Testing
|
255
|
-
|
256
|
-
Rant extends Test::Unit for property testing. The extension is in its own module. So you need to require it.
|
257
|
-
|
258
|
-
<pre><code>
|
259
|
-
require 'rant/check'
|
260
|
-
</code></pre>
|
261
|
-
|
262
|
-
It defines,
|
263
|
-
|
264
|
-
<pre><code>
|
265
|
-
Test::Unit::Assertions#property_of(&block)
|
266
|
-
The block is used to generate random data with a generator. The method returns a Rant::Property instance, that has the method 'check'.
|
267
|
-
</code></pre>
|
268
|
-
|
269
|
-
It's like this, using the gem 'shoulda'
|
270
|
-
|
271
|
-
<pre><code>
|
272
|
-
# checks that integer only generates fixnum.
|
273
|
-
should "generate Fixnum only" do
|
274
|
-
property_of { integer }.check { |i| assert i.is_a?(Integer) }
|
275
|
-
end
|
276
|
-
</code></pre>
|
277
|
-
|
278
|
-
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 Rant#array generates the right sized array, I could say,
|
279
|
-
|
280
|
-
<pre><code>
|
281
|
-
should "generate right sized array" do
|
282
|
-
property_of {
|
283
|
-
len = integer
|
284
|
-
[len,sized(len) { array :integer }]
|
285
|
-
}.check { |(len,arr)|
|
286
|
-
assert_equal len, arr.length
|
287
|
-
}
|
288
|
-
end
|
289
|
-
</code></pre>
|
290
|
-
|
291
|
-
That's about it. Enjoy :)
|
292
|
-
|
293
|
-
|
294
|
-
h1. Copyright
|
295
|
-
|
296
|
-
Copyright (c) 2009 Howard Yeh. See LICENSE for details.
|