devflow-automation

DevFlow Automation - Actions

DevFlow Actions are named shortcuts that a .NET MAUI app explicitly exposes for automation with [DevFlowAction]. Use them to reach useful app states quickly, such as logging in a test user, seeding data, toggling a feature flag, or navigating to a deep screen.

Actions are opt-in. DevFlow does not expose arbitrary reflection invoke; if you need a new shortcut, add an attributed method in app debug/test code, let Hot Reload apply it, then list and invoke the action.

Optional Session Feedback Nudge

If action discovery or invocation exposed repeated DevFlow friction, missing observability, or several workarounds to reach app state, ask whether the user wants to run maui-devflow-session-review to summarize product feedback. Do not run it automatically.

Start by Listing Actions

Always check for available actions early in a DevFlow session:

maui_list_actions

Look for action names and descriptions that match your goal. Common patterns:

• login-* for authentication shortcuts
• seed-* for data population
• navigate-* for deep links or screen setup
• set-* for feature flags or configuration
• reset-* for state cleanup

Invoke an Action

Arguments are passed as a JSON array in parameter order. Omit trailing optional parameters to use their defaults.

maui_invoke_action actionName="login-test-user"
maui_invoke_action actionName="login-test-user" argsJson='["alice@test.com", "secret"]'
maui_invoke_action actionName="seed-catalog" argsJson='[100]'

After invoking an action, verify the state with a screenshot, tree query, or other DevFlow tools:

maui_screenshot

Hot Reload Workflow

If no useful action exists and you can edit the app:

1. Add a public static method annotated with [DevFlowAction].
2. Add [Description] to each parameter so agents know what to pass.
3. Save and let C# Hot Reload apply the change.
4. Call maui_list_actions again.
5. Invoke the new action with maui_invoke_action.

Example:

using System.ComponentModel;
using Microsoft.Maui.DevFlow.Agent.Core;

public static class DebugHelpers
{
    [DevFlowAction("login-test-user", Description = "Log in as the standard test account")]
    public static async Task LoginTestUser(
        [Description("Email address for the test account")] string email = "test@example.com",
        [Description("Password for the test account")] string password = "password123")
    {
        await AuthService.LoginAsync(email, password);
    }
}

Supported Parameter Types

Arguments are converted from JSON to these action parameter types:

Batch Support

Use invoke-action in batches when setup needs several steps:

{
  "actions": [
    { "action": "invoke-action", "name": "login-test-user" },
    { "action": "invoke-action", "name": "seed-catalog", "args": [100] },
    { "action": "tap", "elementId": "btn-advanced" }
  ]
}

Rules for App Developers

• Methods must be public static.
• Parameters should be simple supported types, enums, nullable supported types, arrays, or supported list interfaces.
• Add [Description] to parameters so AI agents know what to pass.
• Prefer returning void, Task, ValueTask, Task<T>, or ValueTask<T> with simple return values.
• Action names should be unique and intention-revealing.

The DevFlow analyzer validates attributed methods:

Common Patterns

Authentication Bypass

maui_list_actions
maui_invoke_action actionName="login-test-user"
maui_screenshot

Data Seeding

maui_invoke_action actionName="seed-catalog" argsJson='[200]'
maui_invoke_action actionName="seed-orders" argsJson='[50, true]'

Feature Flag Override

maui_invoke_action actionName="set-feature-flag" argsJson='["dark-mode", true]'
maui_invoke_action actionName="set-feature-flag" argsJson='["experimental-ui", true]'

Navigate to a Deep Screen

maui_invoke_action actionName="navigate-to" argsJson='["//settings/advanced/network"]'