Package: clatter
clatter is a doctest-style testing tool for command-line applications. It wraps other testing suites and allows them to be tested in docstrings.Free software: MIT licenseDocumentation:https://clatter.readthedocs.io.FeaturesBring testing best practices to your command line appsExtensible - subclassing CommandValidator is trivial using any cli testing suiteEasily test your documentation. This README is a valid doctest!Usage>>>fromclatterimportRunner>>>fromclatter.validatorsimportSubprocessValidatorTest command line utilities and applications by whitelisting them with app-specific testing engines:>>>test_str=r'''
...
... .. code-block:: bash
...
...     $ echo 'Pining for the fjords'
...     Pining for the fjords
... '''>>>>>>tester=Runner()>>>tester.call_engines['echo']=SubprocessValidator()>>>tester.teststring(test_str)Click applicationsIntegrate your command line app:>>>importclick>>>@click.command()...@click.argument('name')...defhello(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
...     <BLANKLINE>
...     Error: Got unexpected extra argument (Parrot)
...
...     $ hello 'Polly Parrot'
...     Hello Polly Parrot!
...
... '''Click applications can be tested with aClickValidatorengine:>>>fromclatter.validatorsimportClickValidator>>>tester=Runner()>>>tester.call_engines['hello']=ClickValidator(hello)>>>tester.teststring(test_str)Mixed applicationsYour 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)Suppressing commandsCommands can be skipped altogether with aSkipValidator:>>>test_str='''
... .. code-block:: bash
...
...     $ aws storage buckets list
...
... '''>>>fromclatter.validatorsimportSkipValidator>>>tester.call_engines['aws']=SkipValidator()>>>tester.teststring(test_str)Illegal commandsErrors 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 +ELLIPSISTraceback(mostrecentcalllast):...ValueError:Command"rm"notallowed.Addcommandcallertocall_enginestowhitelist.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)Error handlingLines 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_WHITESPACETraceback(mostrecentcalllast):...ValueError:Clattertestfailed.There,itmoved!!="No it didn't!"+There,itmoved!-"No it didn't!"Known issuesWe have issues on ourissuespage. But we want to be very up-front about these.SecuritySimilar todoctest, 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 completenessClatter 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_WHITESPACETraceback(mostrecentcalllast):...ValueError:Clattertestfailed.hello>test.txt!=+hello>test.txt-Installationpip install clatterRequirementspytestTodoSeeissuesto see and add to our todos.