readme

README.md

@@ -1,33 +1,33 @@
 pspec
 =====
 
-Python testing for humans.
+Python tests for humans.
 
-Tests shouldn't just be for computers to check your code runs correctly. They can
-also be used by humans to understand your code.
+Tests shouldn't just be for computers to check your code runs correctly. They can also be used by humans to understand what your code does.
 
 pspec tests are designed to be parsed by humans. They look a bit like this:
 
- from pspec import describe, assert_raises
- import random
+```python
+from pspec import describe, assert_raises
+import random
 
- with describe('random'):
-  with describe('shuffle'):
-   def it_does_not_lose_any_elements():
-   seq = range(10)
-   random.shuffle(seq)
-   seq.sort()
-   assert seq == range(10)
+with describe('random'):
+ with describe('shuffle'):
+ def it_does_not_lose_any_elements():
+ seq = range(10)
+ random.shuffle(seq)
+ seq.sort()
+ assert seq == range(10)
 
-  def it_raises_an_exception_for_an_immutable_sequence():
-  with assert_raises(TypeError):
-  random.shuffle((1, 2, 3))
-
-  with describe('choice'):
-  def it_picks_an_element_that_is_in_the_sequence():
-  seq = range(10)
-  assert random.choice(seq) in seq
+ def it_raises_an_exception_for_an_immutable_sequence():
+ with assert_raises(TypeError):
+ random.shuffle((1, 2, 3))
 
+ with describe('choice'):
+ def it_picks_an_element_that_is_in_the_sequence():
+ seq = range(10)
+ assert random.choice(seq) in seq
+```
 
 (Compare with a [similar example for the built-in unittest module](https://docs.python.org/library/unittest.html#basic-example).)
 
@@ -36,8 +36,6 @@ They are run with the `pspec` command:
  $ pspec random_spec.py
 
 
-**Note:** pspec is still in its infancy. Don't expect it to be useful yet.
-
 
 Development install
 -------------------
@@ -48,11 +46,12 @@ Development install
 Goals
 -----
 
+**Note:** pspec is still in its infancy. Don't expect it to be useful yet. Here is some stuff I want to do:
+
  - Human readable tests.
- - Beautiful test reports, with coloured string diffs. (Similar to [Mocha's](https://visionmedia.github.com/mocha/#string diffs))
- - Native assert statement. ([pytest](https://pytest.org/) has the magic needed
- for this)
- - Simple, Pythonic design. (I'm looking at you, unittest and pytest.)
+ - Beautiful test reports with coloured string diffs. (Similar to [Mocha's](https://visionmedia.github.com/mocha/#string diffs))
+ - Native assert statement instead of all the ``assertEqual`` rubbish. ([pytest](https://pytest.org/) has the bits and bobs we need for this)
+ - Simple design.
  - Minimal magic.