Skip to content

fix(executor): a runFlow's or a retry's file runs its own onFlowStart and onFlowComplete, as in Maestro - #277

Merged
omnarayan merged 1 commit into
devicelab-dev:mainfrom
luka-vladika-happening-xyz:fix/runflow-file-runs-its-hooks
Nov 18, 2026
Merged

omnarayan merged 1 commit into
devicelab-dev:mainfrom
luka-vladika-happening-xyz:fix/runflow-file-runs-its-hooks

Conversation

@luka-vladika-happening-xyz

@luka-vladika-happening-xyz luka-vladika-happening-xyz commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

A file reached by runFlow or retry applies only its env:: its header's onFlowStart and onFlowComplete never run. Maestro runs them around the file's commands: runFlowCommand and retryCommand both go through runSubFlow, whose config is the file's header, with onFlowStart before the commands and onFlowComplete in a finally. A sub-flow that sets something up and tears it down (a mocked server, a setting, airplane mode) in its own hooks left it in place here.

Type of Change

  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking change that adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update
  • Refactoring (no functional changes)

Changes Made

  • executeSubFlow: the file's onFlowStart, then its steps unless onFlowStart failed, then its onFlowComplete, also after a failed step. The sub-flow fails when a hook fails ("onFlowStart failed: …" / "onFlowComplete failed: …"), with the first failure, as a flow's own hooks report it. A retry runs them on each attempt.
  • Once the run is cancelled or a runFlow's timeout: has passed, nothing more runs, onFlowComplete included (Maestro skips it on a cancel too).
  • One difference from Maestro, kept on purpose: Maestro takes executeSubflowCommands' result as onFlowStart's success, and that result says whether a command changed the screen (.any { it }), so a file whose onFlowStart is only assertions, extendedWaitUntil, defineVariables or an optional step that failed has its steps silently skipped there. Here they run.
  • The pre-session scan for launchApp (iOS real device: WDA defaultAlertAction not armed from launchApp permissions in onFlowStart / runFlow subflows (silent; diverges from simulator) #108) reads a sub-file's onFlowStart before its steps and its onFlowComplete after them, so a launchApp with permissions in a sub-file's hook arms the driver as one in its steps does.
  • With --pause-on-failure, a failure inside a runFlow's file pauses at the top-level step, so the file's onFlowComplete has run by then: the device is no longer quite as the failure left it.
  • Breaking: every existing runFlow or retry of a file with hooks now runs those hooks.

Related Issues

None open; found comparing runs with Maestro 2.12.1.

Testing

  • Tests pass locally (go test -race ./..., pkg/driver/browser/cdp left out: it launches Chrome)
  • Linting passes (golangci-lint v2.13.2: 0 issues)
  • Added tests for new functionality
  • Tested manually with sample flows

TestRunFlowFileRunsItsOwnHooks (pkg/executor/subflow_hooks_test.go): a runFlow run twice, a retry, a retry that runs the hooks again after a failed attempt, onFlowComplete after a failing step, a failing onFlowStart skipping the steps, a failing onFlowComplete failing the runFlow, an optional hook step that fails, a when: false (no hook runs) and inline commands: (no hooks). TestCollectStepsForPrepare_SubFlowFileHooks: a sub-file's hook launchApps are scanned, onFlowStart's first. On main all but the when: and inline cases fail.

On an Android emulator (API 36), with Maestro 2.12.1 for reference: a file with its own onFlowStart and onFlowComplete (evalScripts counting in output) run twice by runFlow, then a check of the counts, passes on Maestro and with this change.

Checklist

Additional Notes

Proposed CHANGELOG entry:

A file reached by runFlow or retry runs its own onFlowStart and onFlowComplete, as in Maestro (#277). Only the file's env: was applied, so a sub-flow's own setup and teardown never ran. Now onFlowStart runs before the file's steps (a failure skips them), onFlowComplete after them, also after a failure, and the sub-flow fails when a hook does; a retry runs them on each attempt. Unlike Maestro, the steps also run when onFlowStart changed nothing on screen. Breaking: existing runFlows and retrys of files with hooks now run those hooks.

… and onFlowComplete, as in Maestro

A file reached by runFlow or retry applied only its env:; its header's
onFlowStart and onFlowComplete never ran. Maestro runs them around the
file's commands (Orchestra.kt runSubFlow, for runFlowCommand and
retryCommand alike; the command's config is the file's header): the
steps after onFlowStart, onFlowComplete in a finally.

executeSubFlow now runs onFlowStart, then the steps unless it failed,
then onFlowComplete, also after a failed step; the sub-flow fails when a
hook fails, with the first failure, as a flow's own hooks report it. A
retry runs them on each attempt. Once the run is cancelled or a runFlow's
timeout: has passed, nothing more runs, onFlowComplete included (Maestro
skips it on a cancel too). Unlike Maestro, the steps run when onFlowStart
changed nothing on screen: runSubFlow takes executeSubflowCommands'
"screen changed" result as onFlowStart's success, so a hook of only
assertions skips the file's steps there.

The pre-session scan for launchApp reads a sub-file's onFlowStart before
its steps and its onFlowComplete after them, so a launchApp with
permissions in a sub-file's hook arms the driver as one in its steps does.
@codecov

codecov Bot commented Nov 16, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@omnarayan
omnarayan merged commit 5bee994 into devicelab-dev:main Nov 18, 2026
5 checks passed
omnarayan added a commit that referenced this pull request Nov 18, 2026
A retry's final error is its last attempt's, and a failing onFlowStart or
onFlowComplete put its name only in the attempt's message, so the result read
"Retry failed after 3 attempts (cause: element not found)".

Refs #277
omnarayan added a commit that referenced this pull request Nov 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants