Skip to content

Commit 2b16eca

Browse files
gfredericksgfredericks
committed
Overhaul README
Fixes TCHECK-14 Now it's mostly a basic menu of links.
1 parent 8caf4a0 commit 2b16eca

File tree

4 files changed

+186
-200
lines changed

4 files changed

+186
-200
lines changed

‎README.md

+45-200
Original file line numberDiff line numberDiff line change
@@ -5,24 +5,50 @@ The core idea of _test.check_ is that instead of enumerating expected input
55
and output for unit tests, you write properties about your function that should
66
hold true for all inputs. This lets you write concise, powerful tests.
77

8-
* [Releases and Dependency Information](#releases-and-dependency-information)
9-
* [Documentation](#documentation)
10-
* [Developer Information](#developer-information)
11-
* [See also](#see-also)
12-
* [YourKit](#yourkit)
13-
* [License](#license)
14-
15-
## Releases and Dependency Information
16-
17-
Release notes for each version are available in
18-
[`CHANGELOG.markdown`](CHANGELOG.markdown). Remember that prior to version
19-
0.5.7, _test.check_ was called _simple-check_.
8+
* Release Info
9+
* [Latest Releases](#latest-releases)
10+
* [Changelog](CHANGELOG.markdown)
11+
* [Introduction](doc/intro.md)
12+
* Basic Docs
13+
* [API Docs](http://clojure.github.io/test.check/)
14+
* [Cheatsheet](doc/cheatsheet.md)
15+
* [Generator Examples](doc/generator-examples.md)
16+
* [Migrating from SimpleCheck](doc/migrating-from-simple-check.md)
17+
* Useful Libraries
18+
* [test.chuck](https://github.com/gfredericks/test.chuck)
19+
* [collection-check](https://github.com/ztellman/collection-check)
20+
* [herbert](https://github.com/miner/herbert)
21+
* Examples (some of these may refer to simple-check):
22+
* [core.matrix](https://github.com/mikera/core.matrix/blob/c45ee6b551a50a509e668f46a1ae52ade2c52a82/src/test/clojure/clojure/core/matrix/properties.clj)
23+
* [byte-streams](https://github.com/ztellman/byte-streams/blob/b5f50a20c6237ae4e45046f72367ad658090c591/test/byte_streams_simple_check.clj)
24+
* [byte-transforms](https://github.com/ztellman/byte-transforms/blob/c5b9613eebac722447593530531b9aa7976a0592/test/byte_transforms_simple_check.clj)
25+
* [collection-check](https://github.com/ztellman/collection-check)
26+
* Blog posts and videos (some of these may refer to simple-check):
27+
* [Powerful Testing with test.check - Clojure/West 2014](https://www.youtube.com/watch?v=JMhNINPo__g) -- [Slides](https://speakerdeck.com/reiddraper/powerful-testing-with-test-dot-check)
28+
* [Building test.check Generators - Clojure/Conj 2017](https://www.youtube.com/watch?v=F4VZPxLZUdA) - [Slides](https://gfredericks.com/speaking/2017-10-12-generators.pdf)
29+
* [Check your work - 8th Light](http://blog.8thlight.com/connor-mendenhall/2013/10/31/check-your-work.html)
30+
* [Writing simple-check - Reid Draper](http://reiddraper.com/writing-simple-check/)
31+
* [Generative testing in Clojure - Youtube](https://www.youtube.com/watch?v=u0TkAw8QqrQ)
32+
* Advanced Docs
33+
* [Growth and Shrinking](doc/growth-and-shrinking.md)
34+
* Other Implementations
35+
* [QC for Haskell](http://hackage.haskell.org/package/QuickCheck)
36+
* [The significantly more advanced QC for Erlang](http://www.quviq.com/index.html)
37+
* Papers
38+
* [QuickCheck: A Lightweight Tool for Random Testing of Haskell
39+
Programs](http://www.eecs.northwestern.edu/~robby/courses/395-495-2009-fall/quick.pdf)
40+
* Developer Docs
41+
* [Contributing](CONTRIBUTING.md)
42+
* [Developer Information](doc/development.md)
43+
* [Miscellaneous](#miscellaneous)
2044

21-
As of version `0.9.0`, test.check requires Clojure >= `1.7.0`.
45+
## Latest Releases
2246

23-
Please note a
24-
[breaking change for ClojureScript](https://github.com/clojure/test.check/blob/master/CHANGELOG.markdown#080)
25-
in the `0.8.*` releases.
47+
* Release notes for each version are available in [`CHANGELOG.markdown`](CHANGELOG.markdown)
48+
* Remember that prior to version 0.5.7, _test.check_ was called _simple-check_
49+
* As of version `0.9.0`, test.check requires Clojure >= `1.7.0`
50+
* Please note a [breaking change for ClojureScript](https://github.com/clojure/test.check/blob/master/CHANGELOG.markdown#080)
51+
in the `0.8.*` releases.
2652

2753
### Latest Version
2854

@@ -63,190 +89,9 @@ in the `0.8.*` releases.
6389
If you'd like to try a SNAPSHOT version, [add the sonatype repository to your
6490
project](http://dev.clojure.org/display/community/Maven+Settings+and+Repositories).
6591

66-
## Documentation
67-
68-
* [API Docs](http://clojure.github.io/test.check/)
69-
* [Cheatsheet](https://github.com/clojure/test.check/blob/master/doc/cheatsheet.md)
70-
* [Generator writing guide](doc/intro.md)
71-
* Examples (some of these may refer to simple-check):
72-
* [core.matrix](https://github.com/mikera/core.matrix/blob/c45ee6b551a50a509e668f46a1ae52ade2c52a82/src/test/clojure/clojure/core/matrix/properties.clj)
73-
* [byte-streams](https://github.com/ztellman/byte-streams/blob/b5f50a20c6237ae4e45046f72367ad658090c591/test/byte_streams_simple_check.clj)
74-
* [byte-transforms](https://github.com/ztellman/byte-transforms/blob/c5b9613eebac722447593530531b9aa7976a0592/test/byte_transforms_simple_check.clj)
75-
* [collection-check](https://github.com/ztellman/collection-check)
76-
* Blog posts and videos (some of these may refer to simple-check):
77-
* [Powerful Testing with test.check - Clojure/West 2014](https://www.youtube.com/watch?v=JMhNINPo__g) -- [Slides](https://speakerdeck.com/reiddraper/powerful-testing-with-test-dot-check)
78-
* [Building test.check Generators - Clojure/Conj 2017](https://www.youtube.com/watch?v=F4VZPxLZUdA) - [Slides](https://gfredericks.com/speaking/2017-10-12-generators.pdf)
79-
* [Check your work - 8th Light](http://blog.8thlight.com/connor-mendenhall/2013/10/31/check-your-work.html)
80-
* [Writing simple-check - Reid Draper](http://reiddraper.com/writing-simple-check/)
81-
* [Generative testing in Clojure - Youtube](https://www.youtube.com/watch?v=u0TkAw8QqrQ)
82-
83-
## Useful libraries
84-
85-
* [test.chuck](https://github.com/gfredericks/test.chuck)
86-
* [collection-check](https://github.com/ztellman/collection-check)
87-
* [herbert](https://github.com/miner/herbert)
88-
89-
## Examples
90-
91-
Let's say we're testing a sort function. We want to check that that our sort
92-
function is idempotent, that is, applying sort twice should be equivalent to
93-
applying it once: `(= (sort a) (sort (sort a)))`. Let's write a quick test to
94-
make sure this is the case:
95-
96-
```clojure
97-
(require '[clojure.test.check :as tc])
98-
(require '[clojure.test.check.generators :as gen])
99-
(require '[clojure.test.check.properties :as prop #?@(:cljs [:include-macros true])])
100-
101-
(def sort-idempotent-prop
102-
(prop/for-all [v (gen/vector gen/int)]
103-
(= (sort v) (sort (sort v)))))
104-
105-
(tc/quick-check 100 sort-idempotent-prop)
106-
;; => {:result true,
107-
;; => :pass? true,
108-
;; => :num-tests 100,
109-
;; => :time-elapsed-ms 28,
110-
;; => :seed 1528580707376}
111-
```
112-
113-
In prose, this test reads: for all vectors of integers, `v`, sorting `v` is
114-
equal to sorting `v` twice.
115-
116-
What happens if our test fails? _test.check_ will try and find 'smaller'
117-
inputs that still fail. This process is called shrinking. Let's see it in
118-
action:
119-
120-
```clojure
121-
(def prop-sorted-first-less-than-last
122-
(prop/for-all [v (gen/not-empty (gen/vector gen/int))]
123-
(let [s (sort v)]
124-
(< (first s) (last s)))))
125-
126-
(tc/quick-check 100 prop-sorted-first-less-than-last)
127-
;; => {:num-tests 5,
128-
;; => :seed 1528580863556,
129-
;; => :fail [[-3]],
130-
;; => :failed-after-ms 1,
131-
;; => :result false,
132-
;; => :result-data nil,
133-
;; => :failing-size 4,
134-
;; => :pass? false,
135-
;; => :shrunk
136-
;; => {:total-nodes-visited 5,
137-
;; => :depth 2,
138-
;; => :pass? false,
139-
;; => :result false,
140-
;; => :result-data nil,
141-
;; => :time-shrinking-ms 1,
142-
;; => :smallest [[0]]}}
143-
```
144-
145-
This test claims that the first element of a sorted vector should be less-than
146-
the last. Of course, this isn't true: the test fails with input `[-3]`, which
147-
gets shrunk down to `[0]`, as seen in the output above. As your test functions
148-
require more sophisticated input, shrinking becomes critical to being able
149-
to understand exactly why a random test failed. To see how powerful shrinking
150-
is, let's come up with a contrived example: a function that fails if it's
151-
passed a sequence that contains the number 42:
152-
153-
```clojure
154-
(def prop-no-42
155-
(prop/for-all [v (gen/vector gen/int)]
156-
(not (some #{42} v))))
157-
158-
(tc/quick-check 100 prop-no-42)
159-
;; => {:num-tests 45,
160-
;; => :seed 1528580964834,
161-
;; => :fail
162-
;; => [[-35 -9 -31 12 -30 -40 36 36 25 -2 -31 42 8 31 17 -19 3 -15 44 -1 -8 27 16]],
163-
;; => :failed-after-ms 11,
164-
;; => :result false,
165-
;; => :result-data nil,
166-
;; => :failing-size 44,
167-
;; => :pass? false,
168-
;; => :shrunk
169-
;; => {:total-nodes-visited 16,
170-
;; => :depth 5,
171-
;; => :pass? false,
172-
;; => :result false,
173-
;; => :result-data nil,
174-
;; => :time-shrinking-ms 1,
175-
;; => :smallest [[42]]}}
176-
```
177-
178-
We see that the test failed on a rather large vector, as seen in the `:fail`
179-
key. But then _test.check_ was able to shrink the input down to `[42]`, as
180-
seen in the keys `[:shrunk :smallest]`.
181-
182-
To learn more, check out the [documentation](#documentation) links.
183-
184-
### `clojure.test` Integration
185-
186-
The macro `clojure.test.check.clojure-test/defspec` allows you to succinctly
187-
write properties that run under the `clojure.test` runner, for example:
188-
189-
```clojure
190-
(defspec first-element-is-min-after-sorting ;; the name of the test
191-
100 ;; the number of iterations for test.check to test
192-
(prop/for-all [v (gen/not-empty (gen/vector gen/int))]
193-
(= (apply min v)
194-
(first (sort v)))))
195-
```
196-
197-
### ClojureScript
198-
199-
ClojureScript support was added in version `0.7.0`.
200-
201-
Integrating with `cljs.test` is via the
202-
`clojure.test.check.clojure-test/defspec` macro, in the same fashion
203-
as integration with `clojure.test` on the jvm.
204-
205-
## Developer Information
206-
207-
We can not accept pull requests. Please see
208-
[CONTRIBUTING.md](CONTRIBUTING.md) for details.
209-
210-
### Links
211-
212-
* [GitHub project](https://github.com/clojure/test.check)
213-
* [Bug Tracker](http://dev.clojure.org/jira/browse/TCHECK)
214-
* [Continuous Integration](http://build.clojure.org/job/test.check/)
215-
* [Compatibility Test Matrix](http://build.clojure.org/job/test.check-test-matrix/)
216-
217-
### Tests
218-
219-
test.check runs in both jvm-clojure and clojurescript, so testing
220-
comprehensively requires several steps:
221-
222-
* Run `lein test` to run the JVM tests (requires [Leiningen](https://leiningen.org))
223-
* Run `lein cljsbuild once` to run the ClojureScript tests (also requires [node.js](https://nodejs.org))
224-
* To run the same tests in a web browser, open (after running the above command)
225-
`test-runners/run_tests_dev.html` and `test-runners/run_tests_adv.html` and watch the
226-
javascript console for output
227-
* Run `script/test-self-host` to run the self-hosted ClojureScript tests (also requires [node.js](https://nodejs.org))
228-
229-
## See also
230-
231-
### Other implementations
232-
233-
- [QC for Haskell](http://hackage.haskell.org/package/QuickCheck)
234-
- [The significantly more advanced QC for
235-
Erlang](http://www.quviq.com/index.html)
236-
237-
### Papers
238-
239-
- [QuickCheck: A Lightweight Tool for Random Testing of Haskell
240-
Programs](http://www.eecs.northwestern.edu/~robby/courses/395-495-2009-fall/quick.pdf)
241-
242-
### simple-check
243-
244-
_test.check_ used to be called
245-
[_simple-check_](https://github.com/reiddraper/simple-check).
246-
247-
See [migrating from simple-check](doc/migrating-from-simple-check.md).
92+
## Miscellaneous
24893

249-
## YourKit
94+
### YourKit
25095

25196
![YourKit](http://www.yourkit.com/images/yklogo.png)
25297

@@ -258,7 +103,7 @@ YourKit's leading software products:
258103
* <a href="http://www.yourkit.com/java/profiler/index.jsp">YourKit Java Profiler</a> and
259104
* <a href="http://www.yourkit.com/.net/profiler/index.jsp">YourKit .NET Profiler</a>
260105

261-
## License
106+
### License
262107

263108
Copyright © 2014 Rich Hickey, Reid Draper and contributors
264109

‎doc/development.md

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Development
2+
3+
_(i.e., working on test.check itself)_
4+
5+
## Links
6+
7+
* [GitHub project](https://github.com/clojure/test.check)
8+
* [Bug Tracker](http://dev.clojure.org/jira/browse/TCHECK)
9+
* [Continuous Integration](http://build.clojure.org/job/test.check/)
10+
* [Compatibility Test Matrix](http://build.clojure.org/job/test.check-test-matrix/)
11+
12+
## Tests
13+
14+
test.check runs in both jvm-clojure and clojurescript, so testing
15+
comprehensively requires several steps:
16+
17+
* Run `lein test` to run the JVM tests (requires [Leiningen](https://leiningen.org))
18+
* Run `lein cljsbuild once` to run the ClojureScript tests (also requires [node.js](https://nodejs.org))
19+
* To run the same tests in a web browser, open (after running the above command)
20+
`test-runners/run_tests_dev.html` and `test-runners/run_tests_adv.html` and watch the
21+
javascript console for output
22+
* Run `script/test-self-host` to run the self-hosted ClojureScript tests (also requires [node.js](https://nodejs.org))

0 commit comments

Comments
 (0)