> For the complete documentation index, see [llms.txt](https://docs.maestro.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maestro.dev/maestro-flows/workspace-management/design-your-test-architecture/repository-configuration.md). # Repository configuration Many teams adopt a monorepo approach, co-locating Maestro test suites with app source code. This strategy offers several technical advantages: * **Version synchronization**: Tests remain coupled to the codebase version they validate, ensuring historical commits maintain test compatibility * **Atomic changes**: Feature branches can bundle app logic modifications with corresponding test updates in a single pull request * **Simplified CI/CD**: Build pipelines can reference tests directly from the same repository checkout without managing separate test artifact versions ### Repository structure patterns A well-structured repository ensures that your test suite remains maintainable as your application grows. Most Maestro projects are organized around one of two core strategies: | **Strategy** | **User Journeys (Goal-Driven)** | **Feature Tests (Habit-Driven)** | | ----------------- | ------------------------------------------- | ------------------------------------ | | Primary Objective | Funnel completion | Friction reduction | | Best For | E-commerce, Fintech, Food Delivery | Social Media, Content, Entertainment | | User Motivation | Complete a specific task (e.g., Order food) | Continuous engagement and discovery | | Success Metric | Reaching the end of a funnel | Zero-friction interactions | Choosing the right structure helps ensure your automation remains relevant as your app grows. #### User journeys (Goal-driven Apps) This approach is best for E-commerce, food delivery, or fintech (e.g., DoorDash, Uber, Banking) Apps. These apps exist to help users complete a specific task. When a user is hungry, they open the app to order food, once they are fed, they stop using it. * **The Goal**: Success is defined by the user reaching the end of a funnel (e.g., Order Confirmed). * **The Strategy**: Organize your repository by journeys. Focus on end-to-end flows that track variations of the main task (e.g., Delivery vs. Collection, applying coupons, or external payment processors). This pattern often partitions test suites by user segmentation (new vs. existing) and execution context. ``` ├── flows │ ├── config.yaml │ ├── tests │ │ ├── new_users │ │ │ ├── register.yaml │ │ │ └── shopping_first_time_discount.yaml │ │ └── existing_users │ │ ├── account_settings.yaml │ │ ├── deeplink_from_email.yaml │ │ ├── deeplink_from_notification.yaml │ │ ├── login.yaml │ │ ├── shopping.yaml │ │ └── shopping_bulk_buy_discount.yaml │ └── utils │ └── set_discount_code.js └── src └── app └── ``` {% hint style="success" %} #### Technical implementation note To organize your project into a hierarchical structure, you must define the search path in your `config.yaml` using the `flows` key. For example, setting `flows: tests/**` tells Maestro to discover all Flow files within that specific subdirectory using glob syntax. This provides granular control over which tests are executed during local runs or CI/CD pipelines. {% endhint %} #### Feature tests (Habit-driven Apps) This approach is best for social media, content aggregators, or entertainment (e.g., Reddit, Instagram, Spotify) apps. These apps succeed when they reduce friction and keep users engaged. Success is a cumulative experience of many small, slick interactions. * **The Goal**: Success is defined by high engagement and zero friction. * **The Strategy**: Organize your repository by individual features. You need deep coverage for components because one slow spinner or broken interaction can cause a user to drop off. Feature-based organization establishes a structural isomorphism (direct mapping) between test suites and app modules: ``` ├── flows │ ├── config.yaml │ ├── account │ │ └── set_display_name.yaml │ ├── auth │ │ ├── login.yaml │ │ ├── login_invalid.yaml │ │ └── login_locked_account.yaml │ ├── basket │ │ ├── add_to_cart.yaml │ │ └── update_cart.yaml │ └── checkout │ ├── complete_purchase.yaml │ └── save_for_later.yaml └── src └── app ├── account │ └── ├── auth │ └── ├── basket │ └── └── checkout └── ``` ### Nest steps Learn the "Maestro Way" of writing modular, tagged, and parallel-ready tests exploring the [Maestro Best Practices: Structuring your Test Suite](https://maestro.dev/blog/maestro-best-practices-structuring-your-test-suite) article. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.maestro.dev/maestro-flows/workspace-management/design-your-test-architecture/repository-configuration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.