Merge pull request #947 from python-cmd2/pyscript_docs

Further additions to pyscript documenntation for Issue #644

Author: tleonhardt

docs/features/scripting.rst

@@ -94,11 +94,29 @@ where:
 * ``command`` and ``args`` are entered exactly like they would be entered by
   a user of your application.
 
+See python_scripting_ example and associated conditional_ script for more
+information.
+
+Advanced Support
+~~~~~~~~~~~~~~~~
+
+When implementing a command, setting ``self.last_result`` allows for application-specific
+data to be returned to a python script from the command. This can allow python scripts to
+make decisions based on the result of previous application commands.
+
+The application command (default: ``app``) returns a ``cmd2.CommandResult`` for each command.
+The ``cmd2.CommandResult`` object provides the captured output to ``stdout`` and ``stderr``
+while a command is executing. Additionally, it provides the value that command stored in
+``self.last_result``.
+
+Additionally, an external test Mixin plugin has been provided to allow for python based
+external testing of the application. For example, for system integration tests scenarios
+where the python application is a component of a larger suite of tools and components. This
+interface allows python based tests to call commands and validate results as part of a
+larger test suite. See :ref:`plugins/external_test:External Test Plugin`
+
 .. _python_scripting:
    https://github.com/python-cmd2/cmd2/blob/master/examples/python_scripting.py
 
 .. _conditional:
    https://github.com/python-cmd2/cmd2/blob/master/examples/scripts/conditional.py
-
-See python_scripting_ example and associated conditional_ script for more
-information.

docs/index.rst

@@ -67,6 +67,15 @@ Examples
    examples/index
 
 
+Plugins
+=======
+
+.. toctree::
+   :maxdepth: 2
+
+   plugins/index
+
+
 API Reference
 =============
 

docs/plugins/external_test.rst

@@ -0,0 +1,80 @@
+External Test Plugin
+====================
+
+Overview
+~~~~~~~~
+
+.. _cmd2_external_test_plugin:
+   https://github.com/python-cmd2/cmd2-ext-test/
+
+The cmd2_external_test_plugin_ supports testing of a cmd2 application by exposing access cmd2 commands with the same
+context as from within a cmd2 pyscript.  This allows for verification of an application's support for pyscripts and
+enables the cmd2 application to be tested as part of a larger system integration test.
+
+
+Example cmd2 Application
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following short example shows how to mix in the external test plugin to create a fixture for testing
+your cmd2 application.
+
+Define your cmd2 application
+
+.. code-block:: python
+
+    import cmd2
+    class ExampleApp(cmd2.Cmd):
+        """An class to show how to use a plugin"""
+        def __init__(self, *args, **kwargs):
+            # gotta have this or neither the plugin or cmd2 will initialize
+            super().__init__(*args, **kwargs)
+
+        def do_something(self, arg):
+            self.last_result = 5
+            self.poutput('this is the something command')
+
+Defining the test fixture
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In your test, define a fixture for your cmd2 application
+
+.. code-block:: python
+
+    import cmd2_ext_test
+    import pytest
+
+    class ExampleAppTester(cmd2_ext_test.ExternalTestMixin, ExampleApp):
+        def __init__(self, *args, **kwargs):
+            # gotta have this or neither the plugin or cmd2 will initialize
+            super().__init__(*args, **kwargs)
+
+    @pytest.fixture
+    def example_app():
+        app = ExampleAppTester()
+        app.fixture_setup()
+        yield app
+        app.fixture_teardown()
+
+
+Writing Tests
+~~~~~~~~~~~~~
+
+Now write your tests that validate your application using the `app_cmd` function to access
+the cmd2 application's commands. This allows invocation of the application's commands in the
+same format as a user would type. The results from calling a command matches what is returned
+from running an python script with cmd2's pyscript command, which provides stdout, stderr, and
+the command's result data.
+
+.. code-block:: python
+
+    from cmd2 import CommandResult
+
+    def test_something(example_app):
+        # execute a command
+        out = example_app.app_cmd("something")
+
+        # validate the command output and result data
+        assert isinstance(out, CommandResult)
+        assert str(out.stdout).strip() == 'this is the something command'
+        assert out.data == 5
+

docs/plugins/index.rst

@@ -0,0 +1,7 @@
+Plugins
+========
+
+.. toctree::
+   :maxdepth: 1
+
+   external_test

setup.cfg

@@ -13,5 +13,5 @@ use_parentheses = true
 
 [doc8]
 ignore-path=docs/_build,.git,.idea,.pytest_cache,.tox,.venv,.vscode,build,cmd2,examples,tests,cmd2.egg-info,dist,htmlcov,__pycache__,*.egg
-;max-line-length=99
+max-line-length=117
 verbose=0