Workspace management overview

Organize your Maestro workspace with config.yaml, test architecture, tags, and reporting for scalable automation.

Moving from your first test to a full-scale automation suite requires shifting your focus from "how to write a command" to "how to design a system". A well-architected Maestro workspace ensures your tests stay fast, reliable, and easy to maintain as your application evolves.

The anatomy of a workspace

When organizing your workspace, consider the following four pillars:

1

Configuration

A Maestro workspace is centered around the config.yaml file, which settings that apply to your entire test suite or workspace directory. Access the Project configuration guide to learn how to create and manage configuration files for your suite.

2

Architecture

Before writing dozens of tests, you must choose a repository structure that matches your app's business logic. Whether you choose a User Journey or Feature Test model, learning how to organize your test architecture ensures your tests remain scalable and maintainable.

3

Advanced execution

As your suite grows, you need control over how tests are discovered and executed:

• Tags: Categorize Flows (e.g., smoke, production_ready) to run specific subsets of tests.

• Sequential order: While Maestro favors isolated, non-deterministic execution, you can force a strict sequence when validating complex multi-step events.

4

Analysis

Maestro doesn't just tell you if a test passed, it provides the why:

• Reports and artifacts: Generate JUnit (XML) for CI/CD pipelines or human-readable HTML reports with failure screenshots.

• Record your Flow: Record Maestro tests as MP4 videos for debugging and sharing.

• AI insights: Use the --analyze flag to automatically detect spelling errors, layout breaks, and internationalization issues that traditional assertions might miss.

Best practice

Each Flow should be able to run on a completely reset device, even if you are using sequential execution.

Next steps

If you are setting up a new repository, Maestro recommends following this path:

1. Configure your config.yaml using the instructions in Project configuration.

2. Define your folder structure based on the strategies in Design your test architecture.

3. Tag your critical tests to organize and filter execution as described in Test discovery and tags.