Flutter Key Integration Validator

A CLI tool to validate Flutter automation keys and integration test dependencies. Ensures your Flutter app is ready for automated testing with proper key coverage.

Note: This is a desktop CLI tool that uses dart:io for file system operations. It is not compatible with web/WASM environments by design.

🎯 Features

Key Validation: Validates Flutter key usage in source code
- ValueKey declarations
- Key declarations
- find.byValueKey finders
- find.bySemanticsLabel finders
- find.byTooltip finders
Dependency Check: Verifies required test dependencies
Integration Test Setup: Validates test file structure
Colorful Output: Beautiful console output with emojis
Flexible Configuration: YAML-based key definitions
CI/CD Ready: Perfect for automation pipelines

📦 Installation

dart pub global activate flutter_keycheck

🚀 Quick Start

Create a keys configuration file:

# expected_keys.yaml
keys:
  - login_button
  - password_field
  - submit_button
  - help_tooltip
  - user_profile_card

Run the validator:

flutter_keycheck --keys expected_keys.yaml

📋 Usage

Basic Usage

# Check keys in current directory
flutter_keycheck --keys expected_keys.yaml

# Check specific project path
flutter_keycheck --keys keys/production.yaml --path ./my_flutter_app

# Strict mode (fail on extra keys)
flutter_keycheck --keys expected_keys.yaml --strict

# Verbose output
flutter_keycheck --keys expected_keys.yaml --verbose

Command Line Options

Option	Short	Description	Default
`--keys`	`-k`	Path to keys file (.yaml)	required
`--path`	`-p`	Project source root	`.`
`--strict`	`-s`	Fail if integration_test/appium_test.dart is missing	`false`
`--verbose`	`-v`	Show detailed output	`false`
`--help`	`-h`	Show help message	-

📊 Example Output

🎯 [flutter_keycheck] 🔍 Scanning project...

🧩 Keys Check
────────────────────────────────────────────
❌ Missing Keys:
⛔️ login_button
⛔️ forgot_password_link

🧼 Extra Keys:
💡 debug_menu_button
💡 temp_test_key

🔎 Found Keys:
✔️ password_input_field
└── lib/screens/auth/login_screen.dart
✔️ submit_button
└── lib/widgets/forms/auth_form.dart
└── integration_test/auth_test.dart

📦 Dependencies
────────────────────────────────────────────
✔️ integration_test found in pubspec.yaml ✅
✔️ appium_flutter_server found in pubspec.yaml ✅

🧪 Integration Test Setup
────────────────────────────────────────────
✔️ Found integration_test/appium_test.dart ✅
✔️ Appium Flutter Driver initialized ✅

🚨 Final Verdict
────────────────────────────────────────────
❌ Project is NOT ready for automation build.
Missing 2 required keys. Please add them to your widgets.

🔑 Supported Key Types

// ValueKey
TextField(key: const ValueKey('email_input'))
ElevatedButton(key: const ValueKey('login_button'))

// Regular Key
Container(key: const Key('user_avatar'))

2. Test Finders

// Integration tests
await tester.tap(find.byValueKey('login_button'));
await tester.enterText(find.byValueKey('email_input'), 'test@example.com');

// Semantic labels
await tester.tap(find.bySemanticsLabel('Submit Form'));

// Tooltips
await tester.tap(find.byTooltip('Help Information'));

📝 Configuration

YAML Format

keys:
  # Static keys
  - login_button
  - password_field
  - submit_button

  # Dynamic keys (with placeholders)
  - user_card_{userId}
  - game_level_{levelId}

  # Semantic labels
  - 'Welcome Message'
  - 'Error Dialog'

  # Tooltips
  - 'Help Button'
  - 'Settings Menu'

🧪 Appium Flutter Integration Setup

For complete Appium Flutter integration testing setup, follow the official documentation:

📖 Appium Flutter Integration Driver Setup Guide

Quick Setup Steps

Add dependency to pubspec.yaml:

dev_dependencies:
  appium_flutter_server: '>=0.0.27 <1.0.0'

Create integration_test/appium_test.dart:

import 'package:appium_flutter_server/appium_flutter_server.dart';
import 'package:your_app/main.dart';

void main() {
  initializeTest(app: const MyApp());
}

Build your app for testing:

# Android
./gradlew app:assembleDebug -Ptarget=`pwd`/../integration_test/appium_test.dart

# iOS Simulator
flutter build ios integration_test/appium_test.dart --simulator

What flutter_keycheck validates

✅ Widget Keys - ValueKey and Key declarations in your widgets ✅ Test Finders - find.byValueKey, find.bySemanticsLabel, find.byTooltip usage ✅ Dependencies - Required integration_test and appium_flutter_server packages ✅ Test Setup - Proper integration test file structure

🔧 Integration with CI/CD

GitHub Actions

name: Flutter Key Check
on: [push, pull_request]

jobs:
  key-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: dart-lang/setup-dart@v1
      - name: Install flutter_keycheck
        run: dart pub global activate flutter_keycheck
      - name: Validate keys
        run: flutter_keycheck --keys expected_keys.yaml --strict

Pre-commit Hook

#!/bin/sh
# .git/hooks/pre-commit
flutter_keycheck --keys expected_keys.yaml --strict
if [ $? -ne 0 ]; then
  echo "❌ Key validation failed. Please fix the issues above."
  exit 1
fi

🛠️ Development

Running Tests

dart test

Running from Source

dart run bin/flutter_keycheck.dart --keys keys/testing_keys.yaml

💡 Best Practices

Organize Keys by Feature

keys:
  # Authentication
  - login_button
  - signup_link
  - password_field

  # Profile
  - edit_profile_button
  - save_changes_button

Use Descriptive Names

// ✅ Good
ValueKey('user_profile_edit_button')

// ❌ Avoid
ValueKey('btn1')

Keep Keys Consistent

// Use consistent naming convention
ValueKey('login_email_field')
ValueKey('login_password_field')
ValueKey('login_submit_button')

🖥️ Platform Compatibility

This CLI tool is designed for desktop environments only and supports:

✅ Linux (x64)
✅ macOS (x64, ARM64)
✅ Windows (x64)

Not supported:

❌ Web/Browser - Uses dart:io for file system operations
❌ WebAssembly (WASM) - Not compatible with web runtime
❌ Mobile platforms - Designed as a development tool for desktop

Why not web/WASM? This tool performs file system operations using dart:io to scan your Flutter project files, check dependencies in pubspec.yaml, and validate integration test setup. These operations are not available in web/WASM environments by design.

🤝 Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built for Flutter automation testing
Inspired by the need for reliable UI test coverage
Perfect for CI/CD integration
Works seamlessly with Appium Flutter Integration Driver