Create and expose exceptions for libraries to use.

pekkaklarck · pekkaklarck · commit 02bf41434dac · 2020-10-16T02:02:30.000+03:00
- Failure - ContinuableFailure - Error - FatalError - SkipExecution Fixes robotframework#3685.
diff --git a/atest/robot/cli/console/expected_output/dotted_fatal_error.txt b/atest/robot/cli/console/expected_output/dotted_fatal_error.txt
@@ -1,13 +1,13 @@
-Running suite 'Fatal Exception' with 6 tests.
+Running suite 'Fatal Exception' with 8 tests.
 ==============================================================================
-Fxxxxx
+Fxxxxxxx
 ------------------------------------------------------------------------------
 FAIL: Fatal Exception.Python Library Kw.Exit From Python Keyword
-FatalCatastrophyException
+FatalCatastrophyException: BANG!
 ==============================================================================
-Run suite 'Fatal Exception' with 6 tests in *.
+Run suite 'Fatal Exception' with 8 tests in *.
 
 FAILED
-6 tests, 0 passed, 6 failed
+8 tests, 0 passed, 8 failed
 
 Output:  *.xml
diff --git a/atest/robot/running/continue_on_failure.robot b/atest/robot/running/continue_on_failure.robot
@@ -96,6 +96,9 @@ Continue in for loop
 Continuable and regular failure in for loop
     Check Test Case    ${TESTNAME}
 
+robot.api.ContinuableFailure
+    Check Test Case    ${TESTNAME}
+
 *** Keywords ***
 Verify all failures in user keyword    [Arguments]    ${kw}    ${where}
     Check Log Message    ${kw.kws[0].msgs[0]}    ContinuableApocalypseException: 1    FAIL
diff --git a/atest/robot/running/fatal_exception.robot b/atest/robot/running/fatal_exception.robot
@@ -14,6 +14,11 @@ Exit From Java Keyword
     Check Test Case    ${TESTNAME}
     Check Test Case    Test That Should Not Be Run 3
 
+robot.api.FatalError
+    Run Tests    ${EMPTY}    running/fatal_exception/standard_error.robot
+    Check Test Case    ${TESTNAME}
+    Check Test Case    Test That Should Not Be Run
+
 Multiple Suite Aware Exiting
     Run Tests    ${EMPTY}    running/fatal_exception/
     Check Test Case    Exit From Python Keyword
diff --git a/atest/robot/running/test_case_status.robot b/atest/robot/running/test_case_status.robot
@@ -50,3 +50,9 @@ Test Teardown is Run When Setup Fails
 
 Test Setup And Teardown Fails
     Check Test Case    ${TEST NAME}
+
+robot.api.Failure
+    Check Test Case    ${TEST NAME}
+
+robot.api.Error
+    Check Test Case    ${TEST NAME}
diff --git a/atest/testdata/running/StandardExceptions.py b/atest/testdata/running/StandardExceptions.py
@@ -0,0 +1,9 @@
+from robot.api import Failure, Error
+
+
+def failure(msg='I failed my duties'):
+    raise Failure(msg)
+
+
+def error(msg='I errored my duties'):
+    raise Error(msg)
diff --git a/atest/testdata/running/continue_on_failure.robot b/atest/testdata/running/continue_on_failure.robot
@@ -174,6 +174,16 @@ Continuable and regular failure in for loop
     END
     Fail    Should not be executed
 
+robot.api.ContinuableFailure
+    [Documentation]    FAIL ${HEADER}\n\n
+    ...    1) 1\n\n
+    ...    2) 2\n\n
+    ...    3) 3\n\n
+    ...    ${TEARDOWN ERROR}
+    Raise Continuable Failure    1    standard=True
+    Raise Continuable Failure    2    standard=True
+    Fail    3
+    Raise Continuable Failure    Should not be executed
 
 *** Keywords ***
 Continuable Failure In User Keyword In ${where}
diff --git a/atest/testdata/running/fatal_exception/01__python_library_kw.robot b/atest/testdata/running/fatal_exception/01__python_library_kw.robot
@@ -4,7 +4,7 @@ Suite Teardown         Log    Suite Teardown
 
 *** Test Cases ***
 Exit From Python Keyword
-    [Documentation]    FAIL FatalCatastrophyException
+    [Documentation]    FAIL FatalCatastrophyException: BANG!
     [Teardown]    Log    This should be executed
     [Tags]    some tag
     Exit On Failure
diff --git a/atest/testdata/running/fatal_exception/standard_error.robot b/atest/testdata/running/fatal_exception/standard_error.robot
@@ -0,0 +1,12 @@
+*** Settings ***
+Library           Exceptions
+
+*** Test Cases ***
+robot.api.FatalError
+    [Documentation]    FAIL FatalError: BANG!
+    Exit on failure    standard=True
+    Fail    Should not be executed
+
+Test That Should Not Be Run
+    [Documentation]    FAIL Test execution stopped due to a fatal error.
+    Fail    Should not be executed
diff --git a/atest/testdata/running/skip/skiplib.py b/atest/testdata/running/skip/skiplib.py
@@ -1,4 +1,4 @@
-from robot.errors import SkipExecution
+from robot.api import SkipExecution
 
 
 class CustomSkipException(Exception):
diff --git a/atest/testdata/running/test_case_status.robot b/atest/testdata/running/test_case_status.robot
@@ -1,3 +1,6 @@
+*** Settings ***
+Library          StandardExceptions.py
+
 *** Test Case ***
 Test Passes
     [Documentation]    PASS
@@ -76,6 +79,14 @@ Test Setup And Teardown Fails
     Fail    This should not be run
     [Teardown]    Fail    Teardown failure
 
+robot.api.Failure
+    [Documentation]    FAIL I failed my duties
+    Failure
+
+robot.api.Error
+    [Documentation]    FAIL I errored my duties
+    Error
+
 *** Keyword ***
 Do Nothing
     No operation
diff --git a/atest/testdata/standard_libraries/builtin/exit_on_failure.robot b/atest/testdata/standard_libraries/builtin/exit_on_failure.robot
@@ -3,15 +3,15 @@ Library         Exceptions
 
 *** Test Cases ***
 Wait Until Keyword Succeeds
-    [Documentation]  FAIL  FatalCatastrophyException
+    [Documentation]  FAIL  FatalCatastrophyException: BANG!
     Wait Until Keyword Succeeds  1 seconds  0.1 second  Exit On Failure
 
 Run Keyword And Expect Error
-    [Documentation]  FAIL  FatalCatastrophyException
+    [Documentation]  FAIL  FatalCatastrophyException: BANG!
     Run Keyword And Expect Error  *  Exit On Failure
 
 Run Keyword And Ignore Error
-    [Documentation]  FAIL  FatalCatastrophyException
+    [Documentation]  FAIL  FatalCatastrophyException: BANG!
     Run Keyword And Ignore Error  Exit On Failure
 
 Failing Test Case
diff --git a/atest/testdata/standard_libraries/builtin/run_keyword_and_continue_on_failure.robot b/atest/testdata/standard_libraries/builtin/run_keyword_and_continue_on_failure.robot
@@ -83,7 +83,7 @@ Run Keyword And Continue On Failure With Nonexisting Extended Variable
     Fail    Normal failure after continuable failure
 
 Run Keyword And Continue On Failure With Fatal Error
-    [Documentation]    FAIL    FatalCatastrophyException
+    [Documentation]    FAIL    FatalCatastrophyException: BANG!
     Run keyword And Continue On Failure    Exit On Failure
     Fail    This Should Not Be Executed!
 
diff --git a/atest/testresources/testlibs/Exceptions.py b/atest/testresources/testlibs/Exceptions.py
@@ -1,11 +1,19 @@
+from robot.api import ContinuableFailure, FatalError
+
+
 class FatalCatastrophyException(RuntimeError):
     ROBOT_EXIT_ON_FAILURE = True
 
+
 class ContinuableApocalypseException(RuntimeError):
     ROBOT_CONTINUE_ON_FAILURE = True
 
-def exit_on_failure():
-    raise FatalCatastrophyException()
 
-def raise_continuable_failure(msg='Can be continued'):
-    raise ContinuableApocalypseException(msg)
+def exit_on_failure(msg='BANG!', standard=False):
+    exception = FatalError if standard else FatalCatastrophyException
+    raise exception(msg)
+
+
+def raise_continuable_failure(msg='Can be continued', standard=False):
+    exception = ContinuableFailure if standard else ContinuableApocalypseException
+    raise exception(msg)
diff --git a/doc/userguide/src/ExtendingRobotFramework/CreatingTestLibraries.rst b/doc/userguide/src/ExtendingRobotFramework/CreatingTestLibraries.rst
@@ -1687,6 +1687,13 @@ Reporting keyword status is done simply using exceptions. If an executed
 method raises an exception, the keyword status is `FAIL`, and if it
 returns normally, the status is `PASS`.
 
+Normal execution failures and errors can be reported using the standard exceptions
+such as `AssertionError`, `ValueError` and `RuntimeError`. There are, however, some
+special cases explained in the subsequent sections where special exceptions are needed.
+
+Error messages
+''''''''''''''
+
 The error message shown in logs, reports and the console is created
 from the exception type and its message. With generic exceptions (for
 example, `AssertionError`, `Exception`, and
@@ -1748,13 +1755,73 @@ These messages are not visible in log files by default because they are very
 rarely interesting for normal users. When developing libraries, it is often a
 good idea to run tests using `--loglevel DEBUG`.
 
+Exceptions provided by Robot Framework
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Robot Framework provides some exceptions that libraries can use for reporting
+failures and other events. These exceptions exposed via the `robot.api`__ package and
+contain the following:
+
+`Failure`
+    Report failed validation.
+
+    There is no practical difference in using this exception compared to using
+    the standard `AssertionError`. The main benefit of using this exception is
+    that its name is consistent with other provided exceptions.
+
+`ContinuableFailure`
+    Report failed validation but allow continuing execution.
+
+    See the `Continuing test execution despite of failures`_ section below
+    for more information, including how to create a custom exception that
+    has this same behavior.
+
+`Error`
+    Report error in execution.
+
+    Failures related to the system not behaving as expected should typically be
+    reported using the `Failure` exception or the standard `AssertionError`.
+    This exception can be used, for example, if the keyword is used incorrectly.
+    There is no practical difference, other than consistent naming with other
+    provided exceptions, compared to using this exception and the standard
+    `RuntimeError`.
+
+`FatalError`
+    Report error that stops the whole execution.
+
+    See the `Stopping test execution`_ section below for more information,
+    including how to create a custom exception that has this same behavior.
+
+
+`SkipExecution`
+    Mark the executed test or task skipped.
+
+    FIXME! Link to skip section once that's written.
+
+__ https://robot-framework.readthedocs.io/en/master/autodoc/robot.api.html
+
+.. note:: All these exceptions are new in Robot Framework 4.0.
+
 Stopping test execution
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 It is possible to fail a test case so that `the whole test execution is
-stopped`__. This is done simply by having a special `ROBOT_EXIT_ON_FAILURE`
-attribute with `True` value set on the exception raised from the keyword.
-This is illustrated in the examples below.
+stopped`__. The easiest way to accomplish this is using the provided__
+`robot.api.FatalError` exception:
+
+.. sourcecode:: python
+
+    from robot.api import FatalError
+
+
+    def example_keyword():
+        if system_is_not_running():
+            raise FatalError('System is not running!')
+        ...
+
+In addition to using the `robot.api.FatalError` exception, it is possible create
+a custom exception that has a special `ROBOT_EXIT_ON_FAILURE` attribute set to
+a `True` value. This is illustrated by the examples below.
 
 Python:
 
@@ -1771,15 +1838,31 @@ Java:
         public static final boolean ROBOT_EXIT_ON_FAILURE = true;
     }
 
+.. note:: The `robot.api.FatalError` exception is new in Robot Framework 4.0.
+
 __ `Stopping test execution gracefully`_
+__ `Exceptions provided by Robot Framework`_
 
 Continuing test execution despite of failures
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 It is possible to `continue test execution even when there are failures`__.
-The way to signal this from test libraries is adding a special
-`ROBOT_CONTINUE_ON_FAILURE` attribute with `True` value to the exception
-used to communicate the failure. This is demonstrated by the examples below.
+The easiest way to do that is using the provided__ `robot.api.ContinuableFailure`
+exception:
+
+.. sourcecode:: python
+
+    from robot.api import ContinuableFailure
+
+
+    def example_keyword():
+        if something_is_wrong():
+            raise ContinuableFailure('Something is wrong but execution can continue.')
+        ...
+
+An alternative is creating a custom exception that has a special
+`ROBOT_CONTINUE_ON_FAILURE` attribute set to a `True` value.
+This is demonstrated by the examples below.
 
 Python:
 
@@ -1796,7 +1879,10 @@ Java:
         public static final boolean ROBOT_CONTINUE_ON_FAILURE = true;
     }
 
+.. note:: The `robot.api.ContinuableFailure` exception is new in Robot Framework 4.0.
+
 __ `Continue on failure`_
+__ `Exceptions provided by Robot Framework`_
 
 Logging information
 ~~~~~~~~~~~~~~~~~~~
diff --git a/src/robot/api/__init__.py b/src/robot/api/__init__.py
@@ -22,9 +22,13 @@
 
 Currently exposed APIs are:
 
-* :mod:`.logger` module for test libraries' logging purposes.
+* :mod:`.logger` module for libraries' logging purposes.
 
-* :mod:`.deco` module with decorators test libraries can utilize.
+* :mod:`.deco` module with decorators libraries can utilize.
+
+* :mod:`.exceptions` module containing exceptions that libraries can utilize for
+  reporting failures and other events. These exceptions can be imported also directly
+  via :mod:`robot.api` like ``from robot.api import SkipExecution``.
 
 * Various functions and classes for parsing test data to tokens
   or to a higher level model represented as an abstract syntax tree (AST).
@@ -72,3 +76,5 @@
 from robot.reporting import ResultWriter
 from robot.result import ExecutionResult, ResultVisitor
 from robot.running import TestSuite, TestSuiteBuilder
+
+from .exceptions import ContinuableFailure, Failure, FatalError, Error, SkipExecution
diff --git a/src/robot/api/exceptions.py b/src/robot/api/exceptions.py
diff --git a/src/robot/errors.py b/src/robot/errors.py
diff --git a/src/robot/libraries/BuiltIn.py b/src/robot/libraries/BuiltIn.py

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-from robot.errors import SkipExecution`
	`1`	`+from robot.api import SkipExecution`
`2`	`2`
`3`	`3`
`4`	`4`	`class CustomSkipException(Exception):`