Repository configuration

Organize your test repository using User Journey or Feature Test patterns.

Decide where to keep your flows and how to divide the flow folders.

Many teams keep flows inside the app's own repository, next to the source code (this is called a monorepo: one repository that holds several parts of a product). This has two benefits:

• Tests match the app version: each commit has its own matching tests, so checking out an old commit still runs the tests that belong to it.
• Change app and tests together: one pull request can update both the app logic and the matching flows.

Repository structure patterns

Most projects divide flows in one of two ways: by user journey (User Journeys), or by feature (Feature Tests). The table compares them.

How to divide	User Journeys (goal-driven apps)	Feature Tests (habit-driven apps)
Main objective	Users get through a whole process (funnel)	Every small interaction feels smooth
Best for	E-commerce, finance, food delivery	Social media, content, entertainment
What users want	Finish one specific task (e.g., order food)	Keep using and exploring
Success looks like	Reaching the end of a funnel	Nothing that annoys the user

Choosing the right way to divide flows keeps your suite a good fit as the app grows. A funnel is the series of steps a user goes through to finish a task, such as choosing food, paying, and getting a confirmation.

User journeys (Goal-driven Apps)

This approach fits e-commerce, food delivery, or finance apps (e.g., DoorDash, Uber, banking). Users open these apps to finish one task: when hungry they order food, and when done they stop using the app.

• The goal: the user reaches the end of a funnel (e.g., order confirmed).
• The approach: divide folders by journey. Write end-to-end flows (running from start to finish) for each variation of the main task, such as delivery or collection, using a coupon, or paying through an outside provider.

Suites are often also divided by user group (new or existing account).

├── 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
        └── <code here>

Subfolders must be declared in config.yaml

If you divide flows into subfolders as above, declare the search path with the flows key in config.yaml. For example, - tests/** tells Astra Scout to take every flow file in the tests folder and its subfolders (** means any depth of folders). This controls which flows run.

Feature tests (Habit-driven Apps)

This approach fits social media, news, or entertainment apps (e.g., Reddit, Instagram, Spotify). Users stay in these apps when everything feels smooth. A good experience is the sum of many small interactions.

• The goal: users stay engaged and meet nothing that annoys them.
• The approach: divide folders by feature. Test each feature thoroughly, because one slow spinner or one broken interaction is enough to make a user leave.

Each flow folder matches one module of the app, like this:

├── 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
        │   └── <code here>
        ├── auth
        │   └── <code here>
        ├── basket
        │   └── <code here>
        └── checkout
            └── <code here>