Merge pull request #44 from darrenburns/readme-rework

Readme rework

README.md

@@ -2,19 +2,19 @@
 
 ![](https://github.com/darrenburns/ward/workflows/Ward%20CI/badge.svg)
 
-An experimental test runner for Python 3.6+ that is heavily inspired by `pytest`. This project is a work in progress, and is not production ready.
+A modern Python test framework designed to help you find and fix flaws faster.
 
 ![screenshot](https://raw.githubusercontent.com/darrenburns/ward/master/screenshot.png)
 
 ## Features
 
 This project is a work in progress. Some of the features that are currently available in a basic form are listed below.
 
-* Modular setup/teardown with fixtures and dependency injection
-* Colourful, human readable diffs allowing you to quickly pinpoint issues
-* A human readable assertion API
-* Tested on Mac OS, Linux, and Windows
-* stderr/stdout captured during test and fixture execution
+* **Colourful, human readable output:** quickly pinpoint and fix issues with detailed output for failing tests.
+* **Modular test dependencies:** manage test setup/teardown code using modular pytest-style fixtures.
+* **Expect API:** A simple but powerful assertion API inspired by [Jest](https://jestjs.io).
+* **Cross platform:** Tested on Mac OS, Linux, and Windows.
+* **Zero config:** Sensible defaults mean running `ward` with no arguments is enough to get started.
 
 Planned features:
 
@@ -26,14 +26,35 @@ Planned features:
 * Integration with unittest.mock (specifics to be ironed out)
 * Plugin system
 
-## Quick Start
+## Getting Started
 
+Install Ward with `pip install ward`.
 
-Installation: `pip install ward`
+Write your first test in `test_sum.py` (module name must start with `"test"`):
 
-Look for tests recursively and run them: `ward`
+```python
+from ward import expect
+
+def test_one_plus_two_equals_three():  # name must start with "test"
+    expect(1 + 2).equals(3)
+```
+
+Now run your test with `ward` (no arguments needed). Ward will output the following:
+
+```
+ PASS  test_sum.test_one_plus_two_equals_three
+```
 
-## Examples
+*You've just wrote your first test with Ward, congrats!* Look [here](#more-examples) for more examples of
+how to test things with Ward.
+
+## How to Contribute
+
+Contributions are very welcome and encouraged!
+
+See the [contributing guide](.github/CONTRIBUTING.md) for information on how you can take part in the development of Ward.
+
+## More Examples
 
 ### Dependency injection with fixtures
 
@@ -155,6 +176,12 @@ def test_to_be_skipped():
     pass
 ```
 
+### Expecting a test to fail
+
+You can mark a test that you expect to fail with the `@xfail` decorator. If a test
+marked with this decorator passes unexpectedly, the overall run will be
+considered a failure.
+
 ### Testing for approximate equality
 
 Check that a value is close to another value.
@@ -170,5 +197,5 @@ If you wish for Ward to cancel a run immediately after a specific number of fail
 you can use the `--fail-limit` option. To have a run end immediately after 5 tests fail:
 
 ```text
-ward --fail-limit=5
+ward --fail-limit 5
 ```

tests/test_suite.py

@@ -4,7 +4,7 @@
 from ward import expect, fixture
 from ward.fixtures import Fixture, FixtureRegistry
 from ward.suite import Suite
-from ward.test import Test, WardMarker, skip
+from ward.test import Test, WardMarker
 from ward.test_result import TestOutcome, TestResult
 
 NUMBER_OF_TESTS = 5

ward/diff.py

@@ -98,10 +98,12 @@ def build_unified_diff(lhs_repr, rhs_repr, margin_left=4) -> str:
                             output_lines[last_output_idx] += colored(current_span, color="green")
                         elif prev_char in "+^" and prev_marker == "+":
                             output_lines[last_output_idx] += bright_red(
-                                colored(current_span, on_color="on_red", attrs=["bold"]))
+                                colored(current_span, on_color="on_red", attrs=["bold"])
+                            )
                         elif prev_char in "-^" and prev_marker == "-":
                             output_lines[last_output_idx] += bright_green(
-                                colored(current_span, on_color="on_green", attrs=["bold"]))
+                                colored(current_span, on_color="on_green", attrs=["bold"])
+                            )
                         current_span = ""
                     current_span += line_to_rewrite[index - 2]  # Subtract 2 to account for code at start of line
                 prev_char = char
@@ -115,7 +117,6 @@ def build_unified_diff(lhs_repr, rhs_repr, margin_left=4) -> str:
             elif prev_marker == "-":
                 output_lines[last_output_idx] += colored(line_to_rewrite[remaining_index:], color="green")
 
-
         else:
             output_lines.append(line[2:])
         prev_marker = line[0]

ward/terminal.py

@@ -122,11 +122,7 @@ def output_single_test_result(self, test_result: TestResult):
         print(colored(padded_outcome, color="grey", on_color=bg), mod_name + test_result.test.name)
 
     def output_why_test_failed_header(self, test_result: TestResult):
-        print(
-            colored(" Failure", color="red"),
-            "in",
-            colored(test_result.test.qualified_name, attrs=["bold"]),
-        )
+        print(colored(" Failure", color="red"), "in", colored(test_result.test.qualified_name, attrs=["bold"]))
 
     def output_why_test_failed(self, test_result: TestResult):
         truncation_chars = self.terminal_size.width - 24