Refactor exit_code implementation

cmd2.Cmd.cmdloop() now returns self.exit_code which should be an integer

Also:
- Refactored examples to call sys.exit(app.cmdloop()) in their __main__
- Running transcript tests now sets the exit_code accordingly based on success/failure
- Updated CHANGELOG
- Updated README
- Updated Sphinx docs
- Added unit test for case when transcript test fails

3 files changed, 34 insertions, 5 deletions

diff --git a/tests/test_cmd2.py b/tests/test_cmd2.py
index 7a17cfac..1aafefc2 100644
--- a/tests/test_cmd2.py
+++ b/tests/test_cmd2.py
@@ -1950,8 +1950,7 @@ Usage:  exit [exit_code]
 
     def postloop(self) -> None:
         """Hook method executed once when the cmdloop() method is about to return."""
-        code = self.exit_code if self.exit_code is not None else 0
-        self.poutput('exiting with code: {}'.format(code))
+        self.poutput('exiting with code: {}'.format(self.exit_code))
 
 @pytest.fixture
 def exit_code_repl():
@@ -1991,8 +1990,7 @@ def test_exit_code_nonzero(exit_code_repl):
     expected = 'exiting with code: 23\n'
     with mock.patch.object(sys, 'argv', testargs):
         # Run the command loop
-        with pytest.raises(SystemExit):
-            app.cmdloop()
+        app.cmdloop()
     out = app.stdout.getvalue()
     assert out == expected
 
diff --git a/tests/test_transcript.py b/tests/test_transcript.py
index acdbe703..7a2bc38a 100644
--- a/tests/test_transcript.py
+++ b/tests/test_transcript.py
@@ -127,7 +127,8 @@ def test_transcript(request, capsys, filename, feedback_to_output):
     testargs = ['prog', '-t', transcript_file]
     with mock.patch.object(sys, 'argv', testargs):
         # Run the command loop
-        app.cmdloop()
+        sys_exit_code = app.cmdloop()
+        assert sys_exit_code == 0
 
     # Check for the unittest "OK" condition for the 1 test which ran
     expected_start = ".\n----------------------------------------------------------------------\nRan 1 test in"
@@ -247,3 +248,29 @@ def test_parse_transcript_expected(expected, transformed):
 
     testcase = TestMyAppCase()
     assert testcase._transform_transcript_expected(expected) == transformed
+
+
+def test_transcript_failure(request, capsys):
+    # Create a cmd2.Cmd() instance and make sure basic settings are
+    # like we want for test
+    app = CmdLineApp()
+    app.feedback_to_output = False
+
+    # Get location of the transcript
+    test_dir = os.path.dirname(request.module.__file__)
+    transcript_file = os.path.join(test_dir, 'transcripts', 'failure.txt')
+
+    # Need to patch sys.argv so cmd2 doesn't think it was called with
+    # arguments equal to the py.test args
+    testargs = ['prog', '-t', transcript_file]
+    with mock.patch.object(sys, 'argv', testargs):
+        # Run the command loop
+        sys_exit_code = app.cmdloop()
+        assert sys_exit_code != 0
+
+    # Check for the unittest "OK" condition for the 1 test which ran
+    expected_start = "F\n======================================================================\nFAIL: runTest"
+    expected_end = "s\n\nFAILED (failures=1)\nTests failed\n"
+    _, err = capsys.readouterr()
+    assert err.startswith(expected_start)
+    assert err.endswith(expected_end)
diff --git a/tests/transcripts/failure.txt b/tests/transcripts/failure.txt
new file mode 100644
index 00000000..4ef56e72
--- /dev/null
+++ b/tests/transcripts/failure.txt
@@ -0,0 +1,4 @@
+# This is an example of a transcript test which will fail
+
+(Cmd) say -r 3 -s yabba dabba do
+foo bar baz