flutternaut_generator

A CLI tool that scans Flutter projects for Flutternaut widgets and extracts all labels into a structured JSON file. This JSON powers AI-driven test authoring by telling the AI exactly which elements exist in your app.

Installation

Global activation:

bash

dart pub global activate flutternaut_generator

Or add as a dev dependency:

yaml

dev_dependencies:
  flutternaut_generator: ^0.0.1

Usage

Run from your Flutter project root:

bash

# Global activation
flutternaut_generator .

# As a dev dependency
dart run flutternaut_generator

# Custom output path
dart run flutternaut_generator -o keys.json

Configuration

Configure the output path in your project's pubspec.yaml:

yaml

flutternaut_generator:
  output: lib/generated/flutternaut_keys.json

The -o CLI flag takes priority over the pubspec config. If neither is set, defaults to flutternaut_keys.json in the project root.

What it does

Scans all .dart files in lib/
Finds all Flutternaut widget usages (ignores raw Semantics)
Extracts: label, description, constructor type, source file path
Detects dynamic labels (e.g. "todo_$index") and rewrites them as patterns ("todo_{n}")
Outputs flutternaut_keys.json

Output format

json

{
  "generated_at": "2026-03-10T12:00:00.000Z",
  "package": "my_flutter_app",
  "elements": [
    {
      "label": "email_input",
      "type": "input",
      "description": null,
      "file": "lib/screens/login_screen.dart"
    },
    {
      "label": "login_button",
      "type": "button",
      "description": null,
      "file": "lib/screens/login_screen.dart"
    },
    {
      "label": "error_text",
      "type": "text",
      "description": "Shows validation error when login fails",
      "file": "lib/screens/login_screen.dart"
    },
    {
      "label": "todo_text_{n}",
      "type": "item",
      "dynamic": true,
      "description": null,
      "file": "lib/screens/home_screen.dart"
    }
  ]
}

Type mapping

Constructor	Output type
Flutternaut(...)	"element"
Flutternaut.input(...)	"input"
Flutternaut.button(...)	"button"
Flutternaut.text(...)	"text"
Flutternaut.item(...)	"item"
Flutternaut.checkbox(...)	"checkbox"

Dynamic label detection

Labels containing string interpolation are detected and rewritten as patterns:

Source code	Output label	Dynamic
label: "login_button"	login_button	false
label: "todo_$index"	todo_{n}	true
label: "item_${name}_btn"	item_{name}_btn	true

Index-like variables (index, i, n, idx, position, pos) are normalized to {n}.

How it's used

Run the generator in your Flutter project
Upload the flutternaut_keys.json to the Flutternaut desktop app
When you describe a test in natural language, the AI uses the keys to target real elements
The app validates generated test steps against the keys and warns about unknown labels

Requirements

Dart ≥ 3.6.0