Flybirds Documentation

Flybirds is a BDD (Behavior-Driven Development) UI automation testing framework designed for cross-platform and cross-framework testing. It allows you to write test cases in natural language and run the same scripts across multiple platforms including Web, Android, iOS, React Native, and Flutter.

Key capabilities include:

• BDD Pattern: Uses natural language syntax for test cases.
• Multi-Platform Support: Android, iOS, React Native, Flutter, and Web.
• Web Capabilities: Supports Chromium, WebKit, and Firefox engines, including concurrent browser testing.
• Automation Actions: Supports UI element interaction, form submission, validation, keyboard input, and Deeplink navigation.
• Extensibility: A plugin-based architecture allows for custom automation extensions.
• Reporting: Generates HTML reports for test results.

Flybirds is a front-end UI automation test framework based on the BDD (Behavior Driven Development) pattern. It allows developers to write UI automation in natural language.

Core Technologies:

• Behave: Used for BDD to associate natural language test cases with automated code.
• Airtest: Used for mobile UI automation.
• Playwright: Used for web UI automation.

Key Features:

• Supports Android and iOS (iOS in progress) and Web.
• Capabilities include automatic operation, form submission, UI element verification, keyboard input, and deeplink jumping.
• Supports English and Chinese by default.
• Plugin-based architecture for user-defined extensions.
• Provides CLI scaffolding and HTML reports.

A Flybirds project is organized into four main directories to separate configuration, test logic, extensions, and results:

• config: Contains configuration files (e.g., flybirds_config.json, schema_url.json, ele_locator.json).
• features: Contains test case feature files.
• pscript: Contains customized extension scripts (Python) for custom logic, hooks, and parameter processing.
• report: Stores the generated test reports.

A Flybirds project is organized into the following directories:

• config: Contains configuration files for the test environment.
• features: Contains test case feature files.
• pscripts: Contains custom Python extension scripts (custom steps, hooks, etc.).
• report: Stores the generated test reports.

Custom scripts (Python) are stored in the pscript directory to extend the framework's capabilities. Key extension points include:

• custom_handle/operation.py: Define app/web specific behaviors like schema splicing, login/logout, or creating custom BrowserContext instances.
• dsl.step: Define custom DSL statements. Note: If you create a new .py file for steps, you must import it in feature/steps/steps.py.
• dsl.hook: Extend hook functions that run during the execution process.
• params_deal: Store custom parameter processing methods.

Understanding the directory structure helps in locating configuration, plugins, and core logic:

├─ cli                # Scaffolding/CLI tools
├─ core
|   ├─ config_manage.py # Configuration management
|   ├─ dsl
|   |    ├─ globalization # Internationalization handling
|   |    └─ step        # Step list definitions
|   ├─ global_resource.py # Global configuration
|   ├─ launch_cycle     # Lifecycle management
|   └─ plugin
|        ├─ event               # Event management
|        ├─ plugin_manager.py     # Plugin management
|        └─ plugins               # Platform-specific plugins
|             ├─ android         # Android processing
|             ├─ ios            # iOS processing
|             └─ web            # Web processing
├─ report               # Test reports
├─ template             # Template processing
└─ utils               # Utilities

In UI automation, elements are identified by unique attributes rather than visual inspection.

Identification Attributes

When selecting an element, aim for short and unique attributes. Recommended attributes include:

• Copywriting (Text content): The actual text displayed.
• Accessibility Labels: Labels used by assistive technologies.
• ID: Unique identifiers.
• XPath/Location: The structural path of the element.

Verification Logic

To verify if an element meets expected performance, use the following patterns:

• Text Verification: Compare the element's copy attribute against the expected string value.
• Position/List Verification: To verify if an item is the second item in a list, fix the accessibility label for the second item and then validate it by checking its other attributes.

In UI automation, page elements (buttons, text boxes, cards, lists) are organized in a tree structure. To automate interactions, you must identify elements using unique attributes.

Recommended identification methods:

• Text/Copy (文案): The visible text content of the element.
• Accessibility Labels (无障碍标签): Labels used by assistive technologies.

Other available attributes:

• xPath: The positional path in the element tree.
• ID: A unique identifier assigned to the element.

Verification strategies:

• To verify text, compare the element's retrieved text against the expected value.
• To verify position (e.g., checking if an item is the second in a list), use a fixed attribute of the target position (like the accessibility label of the second item) to locate it, then validate its other properties.

Starting from v0.2.3, several new directories are introduced for data comparison and mocking, and an existing directory is renamed:

New Directories

• compareData: Stores files used during service request comparison.
• interfaceIgnoreConfig: Stores configuration files for nodes to be ignored during service request comparison.
• mockCaseData: Stores Mock data that can be bound to monitored service requests.

Renamed Directory

• The app directory located under pscript is replaced by custom_handle. The new custom_handle directory includes additional extension functions for web-related testing.

If you need to run the same scenario multiple times with different sets of variables, use a 场景大纲 (Scenario Outline).

In a Scenario Outline, you use placeholders wrapped in angle brackets (e.g., <variable_name>) within the steps. You then provide an Examples table (represented by a pipe-delimited list) containing the data. The test engine will execute the scenario once for every non-header row in the table.

场景大纲:单程_元素检查
    当   跳转到[列表页]
    而且 等待[5]秒
    那么 存在<元素A>的元素
    那么 不存在<元素B>的元素
    而且 返回上一页

   | 元素A       | 元素B       |
   | 机票价格    | 筛选按钮     |
   | 出发机场    | 退改签浮层   |
   | 到达机场    | 退改签价格   |

Flybirds uses a plugin-based architecture to decouple platform-specific capabilities. Each plugin provides the necessary components, APIs, and configurations required for a specific platform, which Flybirds then injects into the corresponding lifecycle stages.

The framework integrates several core technologies via its plugins:

• Behave: Handles the BDD logic, linking natural language test cases to automation code.
• Airtest: Provides UI automation capabilities for mobile apps (Android/iOS).
• Playwright: Provides UI automation capabilities for Web.
• PaddleOCR & OpenCV: Provides OCR and image recognition capabilities.
• Multiple-cucumber-html-reporter: Generates visual test reports.