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,36 @@ import TaskTesting from '@camunda/task-testing';
 function App() {
   ...
 
-  <TaskTesting api={ ... }>
+  <TaskTesting 
+    api={ ... }
+    onTaskExecutionStarted={ (element) => { ... } }
+    onTaskExecutionFinished={ (element, result) => { ... } }
+  >
     <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)
+
 [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,7 @@ export const SCOPES = {
 /**
  * Emits:
  * - `taskExecution.status.changed` with one of {@link TaskExecutionStatus}
- * - `taskExecution.finished` with {@link TaskExecutionResult}
- * - `taskExecution.error` with {@link TaskExecutionError}
- * - `taskExecution.interrupted` when execution is interrupted by switching focus
+ * - `taskExecution.finished` with {@link TaskExecutionResult} (includes all completion outcomes: success, incident, cancellations, errors)
  */
 export default class TaskExecution extends EventEmitter {
 
@@ -62,10 +60,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');
     });
   }
 
@@ -81,7 +76,6 @@ export default class TaskExecution extends EventEmitter {
     const processId = getProcessId(element);
 
     if (!processId) {
-      this._emitError(`Process ID for element <${element.id}> not found`, null);
       return;
     }
 
@@ -96,17 +90,17 @@ 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.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.cancelTaskExecution();
+      this.cancelTaskExecution('error', error);
 
       return;
     }
@@ -122,16 +116,16 @@ 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.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.cancelTaskExecution('error', error);
       return;
     }
 
@@ -148,7 +142,10 @@ export default class TaskExecution extends EventEmitter {
       }
 
       if (!getProcessInstanceResult.success) {
-        this._emitError('Failed to get process instance', getProcessInstanceResult.error);
+        this.cancelTaskExecution('error', {
+          message: 'Failed to get process instance',
+          response: getProcessInstanceResult.error
+        });
         return;
       }
 
@@ -175,7 +172,10 @@ export default class TaskExecution extends EventEmitter {
         }
 
         if (!getProcessInstanceIncidentResult.success) {
-          this._emitError('Failed to get process instance incident', getProcessInstanceIncidentResult.error);
+          this.cancelTaskExecution('error', {
+            message: 'Failed to get process instance incident',
+            response: getProcessInstanceIncidentResult.error
+          });
           return;
         }
 
@@ -195,7 +195,10 @@ export default class TaskExecution extends EventEmitter {
         }
 
         if (!getProcessInstanceVariablesResult.success) {
-          this._emitError('Failed to get process instance variables', getProcessInstanceVariablesResult.error);
+          this.cancelTaskExecution('error', {
+            message: 'Failed to get process instance variables',
+            response: getProcessInstanceVariablesResult.error
+          });
           return;
         }
 
@@ -209,7 +212,10 @@ export default class TaskExecution extends EventEmitter {
         }
 
         if (!getProcessInstanceElementInstancesResult.success) {
-          this._emitError('Failed to get process instance element instances', getProcessInstanceElementInstancesResult.error);
+          this.cancelTaskExecution('error', {
+            message: 'Failed to get process instance element instances',
+            response: getProcessInstanceElementInstancesResult.error
+          });
           return;
         }
 
@@ -220,10 +226,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,36 +245,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');
-  }
 
-  /**
-   * Emit `taskExecution.error` event.
-   *
-   * @param {string} message
-   * @param {any} [response]
-   */
-  _emitError(message, response) {
-
-    /** @type {import('./types').TaskExecutionError} */
-    const error = {
-      message,
-      response
-    };
-
-    this.emit('taskExecution.error', error);
+    if (wasCanceled && reason) {
+      this.emit('taskExecution.finished', reason === 'error' ? {
+        success: false,
+        reason,
+        error
+      } : {
+        success: false,
+        reason
+      });
+    }
   }
 
   /** @param {TaskExecutionStatus} status */

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 = []
 }) {
 
@@ -204,14 +202,6 @@ export default function TaskTesting({
   // Subscribe to task execution events
   useEffect(() => {
 
-    /** @param {import('../../types').TaskExecutionError} error */
-    const handleError = (error) => {
-      elementConfigRef?.current?.setOutputConfigForElement(element, {
-        success: false,
-        error
-      });
-    };
-
     /**
      * @param {import('../../types').TaskExecutionStatus} status
      * @param {string} [processInstanceKey]
@@ -229,30 +219,39 @@ 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, incident, or error (not user cancellations)
+      if (result.success) {
+        elementConfigRef?.current?.setOutputConfigForElement(element, {
+          success: true,
+          variables: result.variables,
+          operateUrl: currentOperateUrl
+        });
+      } else if (result.reason === 'incident') {
+        elementConfigRef?.current?.setOutputConfigForElement(element, {
+          success: false,
+          variables: result.variables,
+          incident: result.incident,
+          operateUrl: currentOperateUrl
+        });
+      } else if (result.reason === 'error') {
+        elementConfigRef?.current?.setOutputConfigForElement(element, {
+          success: false,
+          error: result.error
+        });
+      }
+      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 +307,7 @@ export default function TaskTesting({
   };
 
   const handleCancelTaskExecution = () => {
-    taskExecutionRef?.current?.cancelTaskExecution();
+    taskExecutionRef?.current?.cancelTaskExecution('user.cancel');
   };
 
   const handleResetOutput = useCallback(() => {

lib/types.d.ts

@@ -77,16 +77,34 @@ export type TaskExecutionStatus =
 
 export type TaskExecutionEvents = 
   'taskExecution.status.changed' |
-  'taskExecution.finished' |
-  'taskExecution.error' |
-  'taskExecution.interrupted';
+  'taskExecution.finished';
 
-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;