Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(play): add scenarios section #4737

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 5 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/components/modeler/web-modeler/img/play-definition.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/components/modeler/web-modeler/img/play-example-data.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/components/modeler/web-modeler/img/play-instance.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/components/modeler/web-modeler/img/play-modifications.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/components/modeler/web-modeler/img/play-rewind.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
38 changes: 36 additions & 2 deletions docs/components/modeler/web-modeler/play-your-process.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,40 @@ Play's rewind operation currently does not support the following elements:
- Play rewinds to an element, not to an element instance. For example, if you wanted to rewind your process to a sequential multi-instance service task which ran five times, it will rewind your process to the first instance of that service task.
- Play rewinds processes by initiating a new instance and executing each element. However, if any element behaves differently from the previous execution, such as a Connector returning a different result, the rewind may fail.

## Scenarios

Scenarios accelerate manual testing by providing a no-code way of quickly re-running processes while tracking your test coverage.

You can validate your process by creating and rerunning scenarios for different paths, ensuring that it continues to function as expected after any changes to your diagram. Scenarios let you replay and confirm that the process completes correctly with the pre-defined actions and variables. Although scenarios are quick to develop and use for non-developers, our [best practices](/components/best-practices/development/testing-process-definitions) suggest using specialized test libraries in your CI/CD pipeline.

### Saving a scenario

After executing a path in your process, you can save it as a scenario by clicking the **Save scenario** button in the process instance header. To view your saved scenarios, navigate to the process definition page by clicking the **View all** button under the Scenarios column in the process instance header.

![save scenario](img/play-save-scenario.png)

### Scenario coverage

Scenario coverage is calculated as the percentage of flow nodes in your process that are covered. This includes all elements, events, and gateways. For example, if 8 out of 10 flow nodes are covered, the coverage will be 80%.
On the process definition page, covered paths are highlighted in blue. You can also click on individual scenarios to view their specific coverage.

![save scenario](img/play-coverage.png)

Once a process instance is completed, the process instance header will display how much your process scenario coverage would increase if this path were saved as a scenario.

### Running a scenario

Scenarios can be run from the process definition page using the **Run all scenarios** button, or by clicking the **Run scenario** button with the play icon for each individual scenario. The result of a scenario execution will be marked as **Completed** or **Failed.** Failed scenarios must be manually updated by clicking the **manually complete and update the scenario** button, especially when changes are made to your diagram that require further user input—such as when a new flow node is added to a previously saved scenario path.

![save scenario](img/play-scenario-runs.png)

### Limitations {#scenarios-limitations}

- Scenarios are stored in the browser's local storage, making them accessible only in the current browser and not usable outside of Play, in a different browser, or by a collaborator.
- Call activities are not supported; therefore, scenarios containing them cannot be executed successfully.
- Scenario paths that include process modifications are not supported.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

variable changes are actually supported
scenarios cover everything rewind feature does

- Similar to process instances, scenarios do not run in isolation. For instance, if two scenario paths are defined for a process and both contain the same message event or signal event, running these scenarios simultaneously may lead to unintended consequences. Publishing a scenario or broadcasting a signal could inadvertently impact the other scenario, resulting in the failure of both.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💭 It could be nice to include a link to the documentation for the nature of message events and signal events, where the issue with global publish/broadcast is mentioned. However, I am not aware of such a link at this moment.


## Modify a process instance

There are two main reasons to modify a process instance in Play:
Expand All @@ -111,7 +145,7 @@ Unlike in [Operate](/components/operate/userguide/process-instance-modification.

![modify process instance](img/play-modifications.png)

### Limitations
### Limitations {#modifications-limitations}

Rewinding a process instance that has modifications applied to is currently not supported. Additionally, some elements do not support specific modifications:

Expand Down Expand Up @@ -177,7 +211,7 @@ Prior to the 8.6 release, Play can be accessed by installing the 8.6.0-alpha [He

After selecting the **Play** tab in Self-Managed, you are prompted to select from the clusters defined in your Web Modeler [configuration](/self-managed/modeler/web-modeler/configuration/configuration.md#clusters). The Camunda 8 Helm and Docker Compose distributions provide one cluster configured by default.

### Limitations
### Limitations {#self-managed-limitations}

- Play does not support multi-tenancy.
- The environment variables `CAMUNDA_CUSTOM_CERT_CHAIN_PATH`, `CAMUNDA_CUSTOM_PRIVATE_KEY_PATH`, `CAMUNDA_CUSTOM_ROOT_CERT_PATH`, and `CAMUNDA_CUSTOM_ROOT_CERT_STRING` can be set in Docker or Helm chart setups. However, these configurations have not been tested with Play's behavior, and therefore are not supported when used with Play.
Expand Down
Loading