feat: simplify and unify execution callbacks

- Unify callbacks into onTaskExecutionFinished with reason field
- Remove onTaskExecutionInterrupted

Result object now uses discriminated union:
- success: true → contains variables
- success: false → contains reason (incident/user.cancel/user.selectionChanged/error)

BREAKING CHANGE: onTaskExecutionInterrupted removed.
Use onTaskExecutionFinished with result.success and result.reason instead.

Related to camunda/camunda-modeler#5597

Author: philippfromme

README.md

@@ -12,13 +12,41 @@ import TaskTesting from '@camunda/task-testing';
 function App() {
   ...
 
-  <TaskTesting api={ ... }>
+  <TaskTesting 
+    api={ ... }
+    onTaskExecutionStarted={ (element) => { ... } }
+    onTaskExecutionFinished={ (element, result) => { ... } }
+    onTaskExecutionError={ (element, error) => { ... } }
+  >
     <TaskTesting.Tab label={ 'Foo' }>...</TaskTesting.Tab>;
     <TaskTesting.Link href="https://camunda.com">Foo</TaskTesting.Link>;
   </TaskTesting>
 }
 ```
 
+### Props
+
+#### Lifecycle Callbacks
+
+The TaskTesting component provides callbacks to track task execution lifecycle events:
+
+- **`onTaskExecutionStarted(element)`** - Called when a task execution begins
+  - `element` - The BPMN element being tested
+
+- **`onTaskExecutionFinished(element, result)`** - Called when task execution ends (success, incident, or cancellation)
+  - `element` - The BPMN element that was tested
+  - `result` - Execution result object:
+    - When `success: true`: Contains `variables` with execution output
+    - When `success: false`: Contains `reason` explaining why:
+      - `'incident'` - Task completed with an incident (includes `incident` and optional `variables`)
+      - `'user.cancel'` - User clicked cancel button
+      - `'user.selectionChanged'` - User selected a different element
+      - `'error'` - Deployment or start instance failed (includes `error` object)
+
+- **`onTaskExecutionError(element, error)`** - Called when deployment or instance start fails (fired before `onTaskExecutionFinished`)
+  - `element` - The BPMN element being tested
+  - `error` - Error object with `message` and `response` details
+
 [See demo](https://github.com/camunda/task-testing/tree/main/demo)
 
 ## Development

demo/App.jsx

@@ -162,6 +162,12 @@ function App() {
           onConfigChanged={ onConfigChanged }
           operateBaseUrl={ operateURL }
           documentationUrl="https://docs.camunda.io/"
+          onTaskExecutionStarted={ (element) => {
+            console.log('Task execution started:', element.id);
+          } }
+          onTaskExecutionFinished={ (element, result) => {
+            console.log('Task execution finished:', element.id, result.success ? 'success' : result.reason, result);
+          } }
         />
       </div>
     </>

lib/TaskExecution.js

@@ -38,9 +38,8 @@ export const SCOPES = {
 /**
  * Emits:
  * - `taskExecution.status.changed` with one of {@link TaskExecutionStatus}
- * - `taskExecution.finished` with {@link TaskExecutionResult}
+ * - `taskExecution.finished` with {@link TaskExecutionResult} (includes all completion outcomes: success, incident, cancellations)
  * - `taskExecution.error` with {@link TaskExecutionError}
- * - `taskExecution.interrupted` when execution is interrupted by switching focus
  */
 export default class TaskExecution extends EventEmitter {
 
@@ -62,10 +61,7 @@ export default class TaskExecution extends EventEmitter {
     const eventBus = injector.get('eventBus');
 
     eventBus.on('selection.changed', () => {
-      if (this._status !== 'idle') {
-        this.emit('taskExecution.interrupted');
-      }
-      this.cancelTaskExecution();
+      this.cancelTaskExecution('user.selectionChanged');
     });
   }
 
@@ -96,17 +92,19 @@ export default class TaskExecution extends EventEmitter {
     }
 
     if (!deploymentResult.success) {
-      this._emitError('Failed to deploy process definition', deploymentResult.error);
-      this.cancelTaskExecution();
+      const error = { message: 'Failed to deploy process definition', response: deploymentResult.error };
+      this._emitError(error.message, error.response);
+      this.cancelTaskExecution('error', error);
       return;
     }
 
     const processDefinitionKey = getProcessDefinitionKey(deploymentResult.response, processId);
 
     if (!processDefinitionKey) {
-      this._emitError('Failed to retrieve process definition key from deployment response', deploymentResult.response);
+      const error = { message: 'Failed to retrieve process definition key from deployment response', response: deploymentResult.response };
+      this._emitError(error.message, error.response);
 
-      this.cancelTaskExecution();
+      this.cancelTaskExecution('error', error);
 
       return;
     }
@@ -122,16 +120,18 @@ export default class TaskExecution extends EventEmitter {
     }
 
     if (!startInstanceResult.success) {
-      this._emitError('Failed to start process instance', startInstanceResult.error);
-      this.cancelTaskExecution();
+      const error = { message: 'Failed to start process instance', response: startInstanceResult.error };
+      this._emitError(error.message, error.response);
+      this.cancelTaskExecution('error', error);
       return;
     }
 
     const processInstanceKey = getProcessInstanceKey(startInstanceResult.response);
 
     if (!processInstanceKey) {
-      this._emitError('Failed to retrieve process instance key from start instance response');
-      this.cancelTaskExecution();
+      const error = { message: 'Failed to retrieve process instance key from start instance response' };
+      this._emitError(error.message);
+      this.cancelTaskExecution('error', error);
       return;
     }
 
@@ -220,10 +220,14 @@ export default class TaskExecution extends EventEmitter {
           element.id
         );
 
-        this.emit('taskExecution.finished', {
-          success: !incident,
+        this.emit('taskExecution.finished', incident ? {
+          success: false,
+          reason: 'incident',
           incident,
           variables
+        } : {
+          success: true,
+          variables
         });
 
         this.cancelTaskExecution();
@@ -235,19 +239,35 @@ export default class TaskExecution extends EventEmitter {
 
   /**
    * Cancel current task execution, clean up and change status to `idle`.
+   *
+   * @param {string} [reason] - Reason for cancellation: 'user.cancel', 'user.selectionChanged', or 'error'
+   * @param {any} [error] - Error object when reason is 'error'
    */
-  async cancelTaskExecution() {
+  async cancelTaskExecution(reason, error) {
 
     // TODO: Proper clean up:
     // - delete process instance
     // - delete process definition
     // - cancel deploy and start instance if they are in progress
 
+    const wasCanceled = this._status !== 'idle';
+
     if (this._interval) {
       clearInterval(this._interval);
     }
 
     this._changeStatus('idle');
+
+    if (wasCanceled && reason) {
+      this.emit('taskExecution.finished', reason === 'error' ? {
+        success: false,
+        reason,
+        error
+      } : {
+        success: false,
+        reason
+      });
+    }
   }
 
   /**

lib/components/TaskTesting/TaskTesting.js

@@ -52,8 +52,7 @@ import { OutputTab } from '../Output/OutputVariables';
  * @param {string} [props.operateBaseUrl]
  * @param {string} [props.documentationUrl]
  * @param {Function} [props.onTaskExecutionStarted=() => {}]
- * @param {Function} [props.onTaskExecutionFinished=() => {}]
- * @param {Function} [props.onTaskExecutionInterrupted=() => {}]
+ * @param {Function} [props.onTaskExecutionFinished=() => {}] - Called with (element, result) where result contains success and optional reason for failures
  * @param {React.ReactNode[]} [props.children=[]]
  */
 export default function TaskTesting({
@@ -71,7 +70,6 @@ export default function TaskTesting({
   documentationUrl,
   onTaskExecutionStarted = () => {},
   onTaskExecutionFinished = () => {},
-  onTaskExecutionInterrupted = () => {},
   children = []
 }) {
 
@@ -229,30 +227,30 @@ export default function TaskTesting({
       }
     };
 
-    /** @param {import('../../types').ElementOutput} output */
-    const handleFinished = (output) => {
-      elementConfigRef?.current?.setOutputConfigForElement(element, {
-        ...output,
-        operateUrl: currentOperateUrl
-      });
-      onTaskExecutionFinished(element, output);
-    };
-
-    const handleInterrupted = () => {
-      onTaskExecutionInterrupted();
+    /** @param {import('../../types').TaskExecutionResult} result */
+    const handleFinished = (result) => {
+
+      // Only save to config if it's a successful execution or incident (not cancellations)
+      if (result.success || result.reason === 'incident') {
+        elementConfigRef?.current?.setOutputConfigForElement(element, {
+          success: result.success,
+          variables: result.variables,
+          incident: result.success ? undefined : result.incident,
+          operateUrl: currentOperateUrl
+        });
+      }
+      onTaskExecutionFinished(element, result);
     };
 
     taskExecutionRef?.current?.on('taskExecution.finished', handleFinished);
     taskExecutionRef?.current?.on('taskExecution.status.changed', handleStatusChange);
     taskExecutionRef?.current?.on('taskExecution.error', handleError);
-    taskExecutionRef?.current?.on('taskExecution.interrupted', handleInterrupted);
 
     return () => {
       if (taskExecutionRef.current) {
         taskExecutionRef.current.off('taskExecution.finished', handleFinished);
         taskExecutionRef.current.off('taskExecution.status.changed', handleStatusChange);
         taskExecutionRef.current.off('taskExecution.error', handleError);
-        taskExecutionRef.current.off('taskExecution.interrupted', handleInterrupted);
       }
     };
   }, [ element, operateBaseUrl, currentOperateUrl ]);
@@ -308,7 +306,7 @@ export default function TaskTesting({
   };
 
   const handleCancelTaskExecution = () => {
-    taskExecutionRef?.current?.cancelTaskExecution();
+    taskExecutionRef?.current?.cancelTaskExecution('user.cancel');
   };
 
   const handleResetOutput = useCallback(() => {

lib/types.d.ts

@@ -78,15 +78,34 @@ export type TaskExecutionStatus =
 export type TaskExecutionEvents = 
   'taskExecution.status.changed' |
   'taskExecution.finished' |
-  'taskExecution.error' |
-  'taskExecution.interrupted';
+  'taskExecution.error';
 
-export type TaskExecutionResult = {
-  success: boolean;
-  variables?: ElementOutputVariables;
-  error?: TaskExecutionError;
-  incident?: any;
-}
+export type TaskExecutionResult = 
+  // Success case - no reason needed
+  | {
+      success: true;
+      variables: ElementOutputVariables;
+    }
+  // Failure cases - always have reason
+  | {
+      success: false;
+      reason: 'incident';
+      incident: any;
+      variables?: ElementOutputVariables;
+    }
+  | {
+      success: false;
+      reason: 'user.cancel';
+    }
+  | {
+      success: false;
+      reason: 'user.selectionChanged';
+    }
+  | {
+      success: false;
+      reason: 'error';
+      error: TaskExecutionError;
+    };
 
 export type TaskExecutionError = {
   message: string;