bashdoctest 0.1.2

Click applications

Integrate your command line app:

>>> import click
>>> @click.command()
... @click.argument('name')
... def hello(name):
...     click.echo('Hello %s!' % name)

This can now be tested in docstrings:

>>> test_str = '''
...
... .. code-block:: bash
...
...     $ hello Polly
...     Hello Polly!
...
...     $ hello Polly Parrot
...     Usage: hello [OPTIONS] NAME
...     Try "hello --help" for help.
...     <BLANKLINE>
...     Error: Got unexpected extra argument (Parrot)
...
...     $ hello 'Polly Parrot'
...     Hello Polly Parrot!
...
... '''

Click applications can be tested with a ClickValidator engine:

>>> from bashdoctest.validators import ClickValidator
>>> tester = Runner()
>>> tester.call_engines['hello'] = ClickValidator(hello)

>>> tester.teststring(test_str)
# hello Polly
# hello Polly Parrot
# hello 'Polly Parrot'

Mixed applications

Your app can be combined with other command-line utilities by adding multiple engines:

>>> test_str = r'''
...
... .. code-block:: bash
...
...     $ hello Polly
...     Hello Polly!
...
...     $ echo 'Pining for the fjords'
...     Pining for the fjords
...
... Pipes/redirects don't work, so we can't redirect this value into a file.
... But we can write a file with python:
...
... .. code-block:: bash
...
...     $ python -c \
...     >     "with open('tmp.txt', 'w+') as f: f.write('Pushing up daisies')"
...
...     $ cat tmp.txt
...     Pushing up daisies
...
... '''

>>> tester.call_engines['echo'] = SubprocessValidator()
>>> tester.call_engines['python'] = SubprocessValidator()
>>> tester.call_engines['cat'] = SubprocessValidator()

>>> tester.teststring(test_str)
# hello Polly
# echo 'Pining for the fjords'
# python -c "with open('tmp.txt', 'w+') as f: f.write('Pushing up daisies')"
# cat tmp.txt

Suppressing commands

Commands can be skipped altogether with a SkipValidator:

>>> test_str = '''
... .. code-block:: bash
...
...     $ aws storage buckets list --password $MY_PASSWORD
...
... '''

>>> from bashdoctest.validators import SkipValidator
>>> tester.call_engines['aws'] = SkipValidator()

>>> tester.teststring(test_str)
# aws storage ...

Illegal commands

Errors are raised when using an application you haven’t whitelisted:

>>> test_str = '''
...
... The following block of code should cause an error:
...
... .. code-block:: bash
...
...     $ rm tmp.txt
...
... '''

>>> tester.teststring(test_str) # doctest: +ELLIPSIS
Traceback (most recent call last):
...
ValueError: Command "rm" not allowed. Add command caller to call_engines to whitelist.

Unrecognized commands will not raise an error if +SKIP is specified

>>> test_str = r'''
...
... .. code-block:: bash
...
...     $ nmake all # doctest: +SKIP
...     $ echo 'I made it!'
...     I made it!
...
... '''
>>> tester.teststring(test_str)
# nmake all

Error handling

Lines failing to match the command’s output will raise an error

>>> test_str = r'''
... .. code-block:: bash
...
...     $ echo "There, it moved!"
...     "No it didn't!"
...
... '''

>>> tester = Runner()
>>> tester.call_engines['echo'] = SubprocessValidator()

>>> tester.teststring(test_str) # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
Traceback (most recent call last):
...
ValueError: Differences (ndiff with -expected +actual):
    - "No it didn't!"
    + There, it moved!

Security

Similar to doctest, executing arbitrary commands from within your tests is dangerous, and we make no attempt to protect you. We won’t run commands you don’t whitelist, but we cant’t prevent against malicious cases. Don’t run anything you don’t understand, and use at your own risk.

Syntactic completeness

Bashhdoctest is not a syntactically complete bash emulator and has no intention of being so.

All arguments to commands are passed as arguments to the first command. Therefore, loops, pipes, redirects, and other control-flow and IO commands will not work as expected.

>>> test_str = '''
...    $ echo hello > test.txt
...    $ cat test.txt
...    hello
...
... '''
>>> tester.teststring(test_str) # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
Traceback (most recent call last):
...
ValueError: Differences (ndiff with -expected +actual):
    + hello > test.txt
<BLANKLINE>