diff --git a/doc/configuring.rst b/doc/configuring.rst index 2f610777..05ec6ffe 100644 --- a/doc/configuring.rst +++ b/doc/configuring.rst @@ -436,3 +436,75 @@ If executing the build step depends on more than one environment variable, use ` For example, ``if_env_set="SPECIAL_TOOL_PATH && ADDITIONAL_SOURCES_ROOT"`` step will be executed only in case of both `$SPECIAL_TOOL_PATH` and `$ADDITIONAL_SOURCES_ROOT` environment variables set to some values. If any of them is missing or not set in current environment, the step will be excluded from current run. + + +Conditional steps +--------------------- + +Conditional step is a :class:`Step` object, that has ``if_succeeded`` or ``if_failed`` parameters with other steps assigned. +If the conditional step succeeds, then the step from the ``if_succeeded`` parameter will be executed. +If the conditional step fails, the step from the ``if_failed`` parameter will be executed instead. + +Configuration example: + +.. testcode:: + + from universum.configuration_support import Configuration, Step + + true_branch_step = Step(name="Positive branch step", command=["ls"]) + false_branch_step = Step(name="Negative branch step", command=["pwd"]) + conditional_step = Step(name="Conditional step", command=["./script.sh"], + if_succeeded=true_branch_step, if_failed=false_branch_step) + + configs = Configuration([conditional_step]) + +Here's the example output for ``script.sh`` returning **zero** exit code: + +.. testoutput:: + + 5. Executing build steps + | 5.1. [ 1/2 ] Conditional step + | | ==> Adding file .../artifacts/Conditional_step_log.txt to artifacts... + | | ==> Execution log is redirected to file + | | $ .../temp/script.sh + | └ [Success] + | + | 5.2. [ 2/2 ] Positive branch step + | | ==> Adding file .../artifacts/Positive_branch_step_log.txt to artifacts... + | | ==> Execution log is redirected to file + | | $ /usr/bin/ls + | └ [Success] + | + └ [Success] + +Here's the example output for ``script.sh`` returning **non-zero** exit code: + +.. testoutput:: + + 5. Executing build steps + | 5.1. [ 1/2 ] Conditional step + | | ==> Adding file .../artifacts/Conditional_step_log.txt to artifacts... + | | ==> Execution log is redirected to file + | | $ .../temp/script.sh + | └ [Success] + | + | 5.2. [ 2/2 ] Negative branch step + | | ==> Adding file .../artifacts/Negative_branch_step_log.txt to artifacts... + | | ==> Execution log is redirected to file + | | $ /usr/bin/pwd + | └ [Success] + | + └ [Success] + +In general, conditional steps behave as any other regular steps, but here are some specifics: + +* Conditional step + * Will always be marked as successful in the log + * TeamCity tag will not be set for the conditional step +* Branch steps + * Only one branch step will be executed + * Both branches' artifacts will be checked for existence before the steps execution + * Artifacts collection or any other side-effects will not be triggered for non-executed branch step + * If chosen branch step is not set, nothing will happen. + For example, if the the ``Step.if_failed`` is not set and conditional step fails during the execution, nothing will happen. + * Only one branch step will be counted for each conditional step at calculating steps numbering and total count diff --git a/universum/configuration_support.py b/universum/configuration_support.py index 9c5e4ac6..91bbaf93 100644 --- a/universum/configuration_support.py +++ b/universum/configuration_support.py @@ -117,7 +117,13 @@ class Step: TeamCity as tags. Every tag is added (if matching condition) after executing build step it is set in, not in the end of all run. Not applicable for conditional steps. fail_tag - A tag used to mark failed TemCity builds. See `pass_tag` for details. Not applicable for conditional steps. + A tag used to mark failed TeamCity builds. See `pass_tag` for details. Not applicable for conditional steps. + if_succeeded + Another step, that will be executed in case of this step will succeed. Having this parameter non-None will + make the current step conditional. + if_failed + Another step, that will be executed in case of this step will fail. Having this parameter non-None will + make the current step conditional. Each parameter is optional, and is substituted with a falsy value, if omitted.