From 706e3264f47931d9cb9ed11f44defd77b3ed84cb Mon Sep 17 00:00:00 2001 From: Jan Richter Date: Tue, 27 Aug 2024 17:14:13 +0200 Subject: [PATCH] [Doc] Avocado instrumented lifecycle This commit adds a new chapter to the reference guide about avocado instrumented tests and its lifecycle. Reference: #5995 Signed-off-by: Jan Richter --- .../chapters/avocado_instrumented.rst | 101 ++++++++++++++++++ docs/source/guides/reference/index.rst | 1 + 2 files changed, 102 insertions(+) create mode 100644 docs/source/guides/reference/chapters/avocado_instrumented.rst diff --git a/docs/source/guides/reference/chapters/avocado_instrumented.rst b/docs/source/guides/reference/chapters/avocado_instrumented.rst new file mode 100644 index 0000000000..e43bf53574 --- /dev/null +++ b/docs/source/guides/reference/chapters/avocado_instrumented.rst @@ -0,0 +1,101 @@ + +The Avocado instrumented lifecycle +================================== + +The Avocado instrumented test goes through multiple phases during +its execution. This page describes in detail each of those phases +and overall lifecycle of instrumented test execution. + +INIT: + This is the initialization state of test. Each test is + created in this state. During the initialization, the test + attributes are set, environment variables are created, and test + skip conditions are evaluated. + +SETUP: + The test is in this state when Test.setUp() method is being + executed. + +TEST: + During this state, the actual test is running. + +TEARDOWN: + During this state, the Test.tearDown() method is being + executed to make clean up after testing. + +FINISHED: + This state is the end of the test's lifecycle, and the test + is in this state when the testing and clean up is finished. + during this phase, the test results are reported to runner and + the testing is finished. + +The whole Test lifecycle is represented by diagram:: + + +--------+ + | | + | INIT +------------+ + | | | + +----+---+ | + | | + | | + Test|initialized | + | | + | Test|skipped + +----v----+ | + | | | + | SETUP +-----------+---+ + | | | | + +----+----+ | | + | | | + | | | + Test|setuped | | + | | | + | | | + +----v---+ | | + | | | | + +-----------+ TEST <------------+ | + | | | | + | +----+---+ Setup|timeout + | | | + | Test finished or timeout | + | | | + | | | + | +------v-----+ | + | | | | + Test|skipped | TEARDOWN <--------------+ + | | | + | +------+-----+ + | | + | | + | Teardown finished or timeout + | | + | | + | +------v-----+ + | | | + +---------> FINISHED | + | | + +------------+ + +Timeouts +~~~~~~~~ + +The avocado instrumented tests can be affected by three types of +timeouts. Test timeout, Task timeout and Job timeout. All of these +timeouts behaves the same from the point of view of Test’s lifecycle, +but the lifecycle will change base on in which state the timeout was +reached. Here is a description of different Test’s lifecycles base +on the interruptions: + +Timeout in SETUP + INIT -> SETUP(interrupted) -> TEARDOWN -> FINISHED (ERROR) + +Timeout in TEST + INIT -> SETUP -> TEST(interrupted) -> TEARDOWN -> FINISHED (INTERRUPTED) + +Timeout in TEARDOWN + INIT -> SETUP -> TEST -> TEARDOWN(interrupted) -> FINISHED (ERROR) + +.. note:: If Task or Job timeout are reached after some other + interruption (test or task timeouts) the test is killed in + the phase where it is (probably TEARDOWN), and it won’t properly + finish. diff --git a/docs/source/guides/reference/index.rst b/docs/source/guides/reference/index.rst index ee7b4fc6b9..5effdb0027 100644 --- a/docs/source/guides/reference/index.rst +++ b/docs/source/guides/reference/index.rst @@ -11,3 +11,4 @@ the core parts. :maxdepth: 2 chapters/runners + chapters/avocado_instrumented