shepherd_tag #

Lightweight tagging system for the Shepherd automation suite.

shepherd_tag lets Flutter developers annotate their widgets and pages with User Story identifiers, enabling the Shepherd CLI to automatically generate Maestro test flows linked to those stories.

Features #

• @ShepherdTag — annotates a contract/constants file with a story id
• ShepherdPageKey — embeds the id into the widget tree via Semantics, making it detectable by Maestro and the Shepherd CLI
• Zero runtime dependencies beyond the Flutter SDK
• No impact on UI layout or behavior

Getting started #

Add shepherd_tag to your pubspec.yaml:

dependencies:
  shepherd_tag: ^0.0.6

Usage #

1. Create a contract file with @ShepherdTag #

// lib/features/auth/auth_tags.dart
import 'package:shepherd_tag/shepherd_tag.dart';

@ShepherdTag(
  id: 'US-001',
  description: 'Login flow with valid credentials',
)
class AuthTags {
  static const String emailField    = 'auth_email_field';
  static const String passwordField = 'auth_password_field';
  static const String submitButton  = 'auth_submit_button';
}

2. Wrap your page with ShepherdPageKey #

// lib/features/auth/presentation/login_page.dart
import 'package:shepherd_tag/shepherd_tag.dart';
import '../auth_tags.dart';

class LoginPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return ShepherdPageKey(
      id: 'US-001',
      child: Scaffold(
        body: Column(
          children: [
            ShepherdElementKey(
              id: AuthTags.emailField,
              child: const TextField(...),
            ),
            ShepherdElementKey(
              id: AuthTags.submitButton,
              child: ElevatedButton(...),
            ),
          ],
        ),
      ),
    );
  }
}

3. Generate the Maestro flow via the Shepherd CLI #

shepherd test gen --story US-001
# Finds all @ShepherdTag(id: 'US-001') in your project
# Generates .maestro/flows/auth/us001_login_test.yaml

API Reference #

@ShepherdTag #

ShepherdPageKey #

Additional information #

• Part of the Shepherd ecosystem
• Report issues at the issue tracker