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

1 files changed, 11 insertions, 6 deletions

diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py
index f5a2a844..f54a0652 100644
--- a/cmd2/cmd2.py
+++ b/cmd2/cmd2.py
@@ -553,8 +553,8 @@ class Cmd(cmd.Cmd):
         # This boolean flag determines whether or not the cmd2 application can interact with the clipboard
         self.can_clip = can_clip
 
-        # This determines if a non-zero exit code should be used when exiting the application
-        self.exit_code = None
+        # This determines the value returned by cmdloop() when exiting the application
+        self.exit_code = 0
 
         # This lock should be acquired before doing any asynchronous changes to the terminal to
         # ensure the updates to the terminal don't interfere with the input being typed or output
@@ -3684,7 +3684,12 @@ class Cmd(cmd.Cmd):
         sys.argv = [sys.argv[0]]  # the --test argument upsets unittest.main()
         testcase = TestMyAppCase()
         runner = unittest.TextTestRunner()
-        runner.run(testcase)
+        test_results = runner.run(testcase)
+        if test_results.wasSuccessful():
+            self.poutput('Tests passed', color=Fore.LIGHTGREEN_EX)
+        else:
+            self.perror('Tests failed', traceback_war=False)
+            self.exit_code = -1
 
     def async_alert(self, alert_msg: str, new_prompt: Optional[str] = None) -> None:  # pragma: no cover
         """
@@ -3932,7 +3937,7 @@ class Cmd(cmd.Cmd):
         """
         self.decolorized_write(sys.stderr, "{}\n".format(message_to_print))
 
-    def cmdloop(self, intro: Optional[str] = None) -> None:
+    def cmdloop(self, intro: Optional[str] = None) -> int:
         """This is an outer wrapper around _cmdloop() which deals with extra features provided by cmd2.
 
         _cmdloop() provides the main loop equivalent to cmd.cmdloop().  This is a wrapper around that which deals with
@@ -3940,6 +3945,7 @@ class Cmd(cmd.Cmd):
         - commands at invocation
         - transcript testing
         - intro banner
+        - exit code
 
         :param intro: if provided this overrides self.intro and serves as the intro banner printed once at start
         """
@@ -4002,8 +4008,7 @@ class Cmd(cmd.Cmd):
         # Restore the original signal handler
         signal.signal(signal.SIGINT, original_sigint_handler)
 
-        if self.exit_code is not None:
-            sys.exit(self.exit_code)
+        return self.exit_code
 
     ###
     #