- commit
- 9f38ed127ed6107164746073bfd25099b6d50f20
- parent
- d9906c9ebd648e5c9818fc929ccda9a82ac831d2
- Author
- Tobias Bengfort <tobias.bengfort@posteo.de>
- Date
- 2019-02-09 13:23
convert README to markdown
Diffstat
| R | README.rst -> README.md | 182 | ++++++++++++++++++++++++++++++++----------------------------- |
1 files changed, 95 insertions, 87 deletions
diff --git a/README.rst b/README.md
@@ -1,127 +1,135 @@1 -1 .. py:decorator:: test(name=None, args=[], decorators=[])-1 1 ## `@test(name=None, args=[], decorators=[])` 2 23 -1 Register a function as a test::-1 3 Register a function as a test: 4 45 -1 import assamtest6 -1 from assamtest import expect-1 5 * `name` (str): The name of this test (defaults to the function name) -1 6 * `args` (list): Arguments that should be passed to the test function -1 7 * `decorators` (list): The test function will be passed through these decorators before being executed 7 88 -1 @assamtest.test(args=['+', 5])9 -1 @assamtest.test(args=['*', 6])10 -1 def my_test(op, value):11 -1 assamtest.expect.equal(eval('2 %s 3' % op), value)-1 9 ```python -1 10 import assamtest -1 11 from assamtest import expect 12 1213 -1 :param str name: The name of this test (defaults to the function name)14 -1 :param list args: Arguments that should be passed to the test function15 -1 :param list decorators: The test function will be passed through these decorators before being executed.-1 13 @assamtest.test(args=['+', 5]) -1 14 @assamtest.test(args=['*', 6]) -1 15 def my_test(op, value): -1 16 assamtest.expect.equal(eval('2 %s 3' % op), value) -1 17 ``` 16 1817 -1 .. py:decorator:: suite(name=None, args=[], decorators=[])-1 19 ## `@suite(name=None, args=[], decorators=[])` 18 2019 -1 Register a function as a suite::-1 21 Register a function as a suite: 20 2221 -1 import assamtest22 -1 from assamtest import expect-1 23 ```python -1 24 import assamtest -1 25 from assamtest import expect 23 2624 -1 @assamtest.suite()25 -1 def my_suite():26 -1 @assamtest.before_each()27 -1 def _before_each():28 -1 pass # do some setup here-1 27 @assamtest.suite() -1 28 def my_suite(): -1 29 @assamtest.before_each() -1 30 def _before_each(): -1 31 pass # do some setup here 29 3230 -1 @assamtest.test()31 -1 def my_test():32 -1 expect.equal(2 + 2, 4)-1 33 @assamtest.test() -1 34 def my_test(): -1 35 expect.equal(2 + 2, 4) -1 36 ``` 33 3734 -1 The optional parameters are the same as for :py:func:`test`.-1 38 The optional parameters are the same as for `test()`. 35 3936 -1 .. py:decorator:: before()37 -1 .. py:decorator:: after()-1 40 ## `@before()` / `@after()` 38 4139 -1 Register a function to run before/after the whole suite.-1 42 Register a function to run before/after the whole suite. 40 4341 -1 There can be only one before/after function per suite.-1 44 There can be only one `before`/`after` function per suite. 42 4543 -1 .. py:decorator:: before_each()44 -1 .. py:decorator:: after_each()-1 46 ## `@before_each()` / `@after_each()` 45 4746 -1 Register a function to run before/after every test.-1 48 Register a function to run before/after every test. 47 4948 -1 There can be only one before_each/after_each function per suite.-1 50 There can be only one `before_each`/`after_each` function per suite. 49 5150 -1 .. py:data:: expect-1 52 ## `expect` 51 5352 -1 A wrapper around the asserts from :py:class:`unittest.TestCase` using snake53 -1 case::-1 54 A wrapper around the asserts from `unittest.TestCase` using snake case: 54 5555 -1 from assamtest import expect-1 56 ```python -1 57 from assamtest import expect 56 5857 -1 expect.equal(2 + 2, 4)58 -1 expect.not_equal(2 + 2, 5)59 -1 expect._in(2, [1, 2, 3])60 -1 with expect.raises(KeyError):61 -1 {'foo': 0}['bar']-1 59 expect.equal(2 + 2, 4) -1 60 expect.not_equal(2 + 2, 5) -1 61 expect._in(2, [1, 2, 3]) -1 62 with expect.raises(KeyError): -1 63 {'foo': 0}['bar'] -1 64 ``` 62 6563 -1 See also the `full list of available assertions64 -1 <https://docs.python.org/3/library/unittest.html?highlight=unittest%20testcase#assert-methods>`_.-1 66 See also the [full list of available assertions](https://docs.python.org/3/library/unittest.html?highlight=unittest%20testcase#assert-methods>). 65 6766 -1 .. py:exception:: Outcome(err, status, level)-1 68 ## `@decorators.skip` 67 6968 -1 Can be used to implement custom outcomes.-1 70 Do not execute the test at all:: 69 7170 -1 :param Exception|str|None err: the reason for this outcome, e.g. an exception or a helpful message71 -1 :param str status: the status, e.g. "passed", "failed", or "skipped"72 -1 :param 'SUCCESS'|'INFO'|'WARNING'|'ERROR' level: a hint for the reporter how this outcome should be interpreted-1 72 ```python -1 73 import assamtest -1 74 from assamtest import expect -1 75 from assamtest.decorators import skip 73 7674 -1 A good example of how this can be used is :py:func:`decorators.skip`::-1 77 @assamtest.test(decorators=[skip]) -1 78 def my_test(): -1 79 expect.equal(2 + 2, 5) -1 80 ``` 75 8176 -1 import functools77 -1 from assamtest import Outcome-1 82 ## `@decorators.fail` 78 8379 -1 def skip(fn):80 -1 @functools.wraps(fn)81 -1 def wrapper(*args, **kwargs):82 -1 raise Outcome(None, 'skipped', 'INFO')83 -1 return wrapper-1 84 Invert the result of the test: If it would fail, pass instead. If it would -1 85 pass, fail instead:: 84 8685 -1 .. py:module:: decorators-1 87 ```python -1 88 import assamtest -1 89 from assamtest import expect -1 90 from assamtest.decorators import fail 86 9187 -1 .. py:decorator:: skip-1 92 @assamtest.test(args=[4]) -1 93 @assamtest.test(args=[5], decorators=[fail]) -1 94 def my_test(value): -1 95 expect.equal(2 + 2, value) -1 96 ``` 88 9789 -1 Do not execute the test at all::-1 98 ## `@decorator.synchronize` 90 9991 -1 import assamtest92 -1 from assamtest import expect93 -1 from assamtest.decorators import skip-1 100 Start an asyncio event loop for the test and wait for it to complete:: 94 10195 -1 @assamtest.test(decorators=[skip])96 -1 def my_test():97 -1 expect.equal(2 + 2, 5)-1 102 ```python -1 103 import asyncio 98 10499 -1 .. py:decorator:: fail-1 105 import assamtest -1 106 from assamtest import expect -1 107 from assamtest.decorators import synchronize 100 108101 -1 Invert the result of the test: If it would fail, pass instead. If it would102 -1 pass, fail instead::-1 109 @assamtest.test() -1 110 @synchronize -1 111 async def my_test(): -1 112 await asyncio.sleep(0.1) -1 113 expect.equal(2 + 2, 4) -1 114 ``` 103 115104 -1 import assamtest105 -1 from assamtest import expect106 -1 from assamtest.decorators import fail-1 116 ## `Outcome(err, status, level)` 107 117108 -1 @assamtest.test(args=[4])109 -1 @assamtest.test(args=[5], decorators=[fail])110 -1 def my_test(value):111 -1 expect.equal(2 + 2, value)-1 118 Can be used to implement custom outcomes. 112 119113 -1 .. py:decorator:: synchronize-1 120 * `err` (Exception|str|None): The reason for this outcome, e.g. an exception or a helpful message -1 121 * `status` (str): The status, e.g. 'passed', 'failed', or 'skipped' -1 122 * `level` ('SUCCESS'|'INFO'|'WARNING'|'ERROR'): A hint for the reporter how this outcome should be interpreted 114 123115 -1 Start an asyncio event loop for the test and wait for it to complete::-1 124 A good example of how this can be used is `decorators.skip()`: 116 125117 -1 import asyncio-1 126 ```python -1 127 import functools -1 128 from assamtest import Outcome 118 129119 -1 import assamtest120 -1 from assamtest import expect121 -1 from assamtest.decorators import synchronize122 -1123 -1 @assamtest.test()124 -1 @synchronize125 -1 async def my_test():126 -1 await asyncio.sleep(0.1)127 -1 expect.equal(2 + 2, 4)-1 130 def skip(fn): -1 131 @functools.wraps(fn) -1 132 def wrapper(*args, **kwargs): -1 133 raise Outcome(None, 'skipped', 'INFO') -1 134 return wrapper -1 135 ```