Getting Started

You only need two things:

• Flutter SDK installed and on your PATH
• An Android emulator or iOS simulator running (or a physical device connected via USB)

Add flutternaut to your Flutter project:

flutter pub add flutternaut

Then import it:

import 'package:flutternaut/flutternaut.dart';

Wrap the widgets you want to test with Flutternaut constructors. Each wrapper gives the element a label that the test engine uses to find and interact with it.

Here's a login screen with three wrapped elements:

@FlutternautView('Login')
class LoginScreen extends StatefulWidget {
  const LoginScreen({super.key});

  @override
  State<LoginScreen> createState() => _LoginScreenState();
}

class _LoginScreenState extends State<LoginScreen> {
  final _emailController = TextEditingController();
  final _passwordController = TextEditingController();

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Flutternaut.input(
          label: 'email_input',
          child: TextField(controller: _emailController),
        ),
        Flutternaut.input(
          label: 'password_input',
          child: TextField(controller: _passwordController),
        ),
        Flutternaut.button(
          label: 'login_button',
          child: ElevatedButton(
            onPressed: _login,
            child: Text('Login'),
          ),
        ),
      ],
    );
  }
}

The @FlutternautView('Login') annotation groups these elements under the "Login" view so the AI knows which screen they belong to. See the full API reference for all constructors.

Run the generator from your Flutter project root:

dart run flutternaut

This scans your project for all Flutternaut widgets and creates a flutternaut_keys.json file:

{
  "elements": [
    { "label": "email_input",    "type": "input",  "view": "Login" },
    { "label": "password_input", "type": "input",  "view": "Login" },
    { "label": "login_button",   "type": "button", "view": "Login" }
  ]
}

This JSON tells the desktop app (and the AI) exactly which elements exist in your app. No hallucinated selectors — only real targets.

Download Flutternaut for macOS or Windows. Open the app and it will automatically:

1. Start the test engine
2. Start the bundled Appium server
3. Detect connected devices and emulators

Once ready, you'll see the dashboard:

Before building tests, load your flutternaut_keys.json into the app. This is how the test editor and AI chat know which elements are available in your app.

• Test Editor — set the keys file as your "Keys Project" in the editor toolbar
• AI Chat — upload the keys file in the chat so the AI targets real elements

Open the Config Editor tab. Two default configurations (Android and iOS) are pre-created — select the one that matches your platform.

1. Drag & drop your APK (Android) or .app/.ipa (iOS) file into the app file drop zone
2. The package name or bundle ID is automatically extracted from the file
3. For physical iOS devices: enter your Xcode Team ID in the iOS Signing section
4. Click Save

The default configs have sensible timeouts and settings. You can adjust them later or create custom configs with the + button.

You have two ways to create tests. Pick whichever feels right:

Option A: Visual Step Editor

Open the Editor tab and build your test step by step:

1. Click Add Step and search for type
2. Set target to email_input and value to [email protected]
3. Add another type step for password_input
4. Add a tap step targeting login_button
5. Select your device, pick a config, and click Run

Option B: AI Chat

Open the AI Chat tab and describe what you want to test:

The AI generates every step using your actual app elements from the keys file. Review the generated test, edit if needed, and run it directly from the chat.

Free accounts include 10 AI messages per day. Need more? Upgrade to Pro.

Want to see everything working before adding Flutternaut to your own project? The flutternaut package includes a complete example app with pre-built tests.

# Clone the repo
git clone https://github.com/KhaledMoSha/flutternaut.git
cd flutternaut/packages/flutternaut/example

# Install dependencies and run on your emulator
flutter pub get
flutter run

The example includes:

• A multi-screen Flutter app (login, todo list, gestures, control flow)
• All widgets already wrapped with Flutternaut
• Pre-generated flutternaut_keys.json
• Sample test files in testdata/ — ready to run in the desktop app

Load the example's keys file and any test from testdata/ into the desktop app to see a full test run in action.

• flutternaut package — Full API reference and all constructors
• flutternaut_generator — CLI tool, output format, and configuration
• Desktop App Guide — Dashboard, device manager, config editor, and reports
• Test Editor Guide — All actions, control flow, and advanced patterns