diff options
| -rw-r--r-- | CHANGELOG.md | 4 | ||||
| -rwxr-xr-x | README.md | 6 | ||||
| -rw-r--r-- | docs/transcript.rst | 27 |
3 files changed, 29 insertions, 8 deletions
diff --git a/CHANGELOG.md b/CHANGELOG.md index 24c11dec..815b8bc8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,4 @@ -## 0.8.0 (TBD, 2018) +## 0.8.0 (February TBD, 2018) * Bug Fixes * Fixed unit tests on Python 3.7 due to changes in how re.escape() behaves in Python 3.7 * Fixed a bug where unknown commands were getting saved in the history @@ -21,7 +21,7 @@ * The **set** command now has an additional **-a/--all** option to also display read-only settings * The **history** command can now run, edit, and save prior commands, in addition to displaying prior commands. * The **history** command can now automatically generate a transcript file for regression testing - * This feature works imperfectly at the moment, but it is still quite useful + * This makes creating regression tests for your ``cmd2`` application trivial * Commands Removed * The **cmdenvironment** has been removed and its functionality incorporated into the **-a/--all** argument to **set** * The **show** command has been removed. Its functionality has always existing within **set** and continues to do so @@ -36,7 +36,13 @@ Main Features - Windows, macOS, and Linux support - Trivial to provide built-in help for all commands - Built-in regression testing framework for your applications (transcript-based testing) +- Transcripts for use with built-in regression can be automatically generated from `history -t` +<aside class="notice"> +**Support for Python 2.7 will be discontinued on Aug 31, 2018**. The use of **Python 3** is *highly* +preferred over Python 2. Consider upgrading your applications and infrastructure if you find +yourself still using Python 2 in production today. +</aside> Installation ------------ diff --git a/docs/transcript.rst b/docs/transcript.rst index f1e3e63f..a2db3efd 100644 --- a/docs/transcript.rst +++ b/docs/transcript.rst @@ -13,6 +13,21 @@ from commands that produce dynamic or variable output. Creating a transcript ===================== +Automatically +------------- +A transcript can automatically generated based upon commands previously executed in the *history*:: + + (Cmd) help + ... + (Cmd) help history + ... + (Cmd) history 1:2 -t transcript.txt + 2 commands and outputs saved to transcript file 'transcript.txt' + +This is by far the easiest way to generate a transcript. + +Manually +-------- Here's a transcript created from ``python examples/example.py``:: (Cmd) say -r 3 Goodnight, Gracie @@ -38,9 +53,9 @@ lines of the transcript as comments:: # Lines at the beginning of the transcript that do not ; start with the prompt i.e. '(Cmd) ' are ignored. /* You can use them for comments. */ - + All six of these lines before the first prompt are treated as comments. - + (Cmd) say -r 3 Goodnight, Gracie Goodnight, Gracie Goodnight, Gracie @@ -105,21 +120,21 @@ the path instead of specifying it verbatim, or we can escape the slashes:: trailing spaces which are impossible to see. Instead of leaving them invisible, you can add a regular expression to match them, so that you can see where they are when you look at the transcript:: - + (Cmd) set prompt 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. - + 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 |