diff options
Diffstat (limited to 'docs/features/transcripts.rst')
| -rw-r--r-- | docs/features/transcripts.rst | 76 |
1 files changed, 41 insertions, 35 deletions
diff --git a/docs/features/transcripts.rst b/docs/features/transcripts.rst index eeb51534..e4ff79a5 100644 --- a/docs/features/transcripts.rst +++ b/docs/features/transcripts.rst @@ -9,12 +9,12 @@ from commands that produce dynamic or variable output. .. highlight:: none -Creating a transcript -===================== -Automatically from history --------------------------- -A transcript can automatically generated based upon commands previously executed in the *history* using ``history -t``:: +Creating From History +--------------------- + +A transcript can automatically generated based upon commands previously executed +in the *history* using ``history -t``:: (Cmd) help ... @@ -27,23 +27,28 @@ This is by far the easiest way to generate a transcript. .. warning:: - Make sure you use the **poutput()** method in your ``cmd2`` application for generating command output. This method - of the ``cmd2.Cmd`` class ensure that output is properly redirected when redirecting to a file, piping to a shell + Make sure you use the **poutput()** method in your ``cmd2`` application for + generating command output. This method of the ``cmd2.Cmd`` class ensure that + output is properly redirected when redirecting to a file, piping to a shell command, and when generating a transcript. -Automatically from a script file --------------------------------- + +Creating From A Script File +--------------------------- + A transcript can also be automatically generated from a script file using ``run_script -t``:: (Cmd) run_script scripts/script.txt -t transcript.txt 2 commands and their outputs saved to transcript file 'transcript.txt' (Cmd) -This is a particularly attractive option for automatically regenerating transcripts for regression testing as your ``cmd2`` -application changes. +This is a particularly attractive option for automatically regenerating +transcripts for regression testing as your ``cmd2`` application changes. + + +Creating Manually +----------------- -Manually --------- Here's a transcript created from ``python examples/example.py``:: (Cmd) say -r 3 Goodnight, Gracie @@ -82,7 +87,8 @@ lines of the transcript as comments:: maybe we could like go to er lunch right? In this example I've used several different commenting styles, and even bare -text. It doesn't matter what you put on those beginning lines. Everything before:: +text. It doesn't matter what you put on those beginning lines. Everything +before:: (Cmd) say -r 3 Goodnight, Gracie @@ -90,14 +96,14 @@ will be ignored. Regular Expressions -=================== +------------------- -If we used the above transcript as-is, it would likely fail. As you can see, -the ``mumble`` command doesn't always return the same thing: it inserts random -words into the input. +If we used the above transcript as-is, it would likely fail. As you can see, the +``mumble`` command doesn't always return the same thing: it inserts random words +into the input. -Regular expressions can be included in the response portion of a transcript, -and are surrounded by slashes:: +Regular expressions can be included in the response portion of a transcript, and +are surrounded by slashes:: (Cmd) mumble maybe we could go to lunch /.*\bmaybe\b.*\bcould\b.*\blunch\b.*/ @@ -141,24 +147,24 @@ the path instead of specifying it verbatim, or we can escape the slashes:: prompt: (Cmd)/ / Some terminal emulators strip trailing space when you copy text from them. - This could make the actual data generated by your app different than the - text you pasted into the transcript, and it might not be readily obvious why - the transcript is not passing. Consider using :ref:`output_redirection` to - the clipboard or to a file to ensure you accurately capture the output of - your command. + This could make the actual data generated by your app different than the text + you pasted into the transcript, and it might not be readily obvious why the + transcript is not passing. Consider using :ref:`output_redirection` to the + clipboard or to a file to ensure you accurately capture the output of your + command. - If you aren't using regular expressions, make sure the newlines at the end - of your transcript exactly match the output of your commands. A common cause - of a failing transcript is an extra or missing newline. + If you aren't using regular expressions, make sure the newlines at the end of + your transcript exactly match the output of your commands. A common cause of + a failing transcript is an extra or missing newline. If you are using regular expressions, be aware that depending on how you - write your regex, the newlines after the regex may or may not matter. - ``\Z`` matches *after* the newline at the end of the string, whereas - ``$`` matches the end of the string *or* just before a newline. + write your regex, the newlines after the regex may or may not matter. ``\Z`` + matches *after* the newline at the end of the string, whereas ``$`` matches + the end of the string *or* just before a newline. -Running a transcript -==================== +Running A Transcript +-------------------- Once you have created a transcript, it's easy to have your application play it back and check the output. From within the ``examples/`` directory:: @@ -177,8 +183,8 @@ output matches the expected result from the transcript. .. note:: If you have set ``allow_cli_args`` to False in order to disable parsing of - command line arguments at invocation, then the use of ``-t`` or ``--test`` - to run transcript testing is automatically disabled. In this case, you can + command line arguments at invocation, then the use of ``-t`` or ``--test`` to + run transcript testing is automatically disabled. In this case, you can alternatively provide a value for the optional ``transcript_files`` when constructing the instance of your ``cmd2.Cmd`` derived class in order to cause a transcript test to run:: |