Skip to main content

conalyz.yaml Reference

conalyz.yaml tells Conalyz how to drive your app in automated mode. Place it in the directory you run conalyz from, or pass a custom path with --config.

Structure​

# steps: lists actions in order. Use analyse to capture and check the current screen.
# Screens without an analyse step are navigated through without capturing.

flow:
  - screen: <screen name>
    steps:
      - <step>
      - <step>

Each entry in flow defines one screen. Steps execute in order — mix analyse, navigation actions, wait_for, and delay in any sequence that matches what your app needs.

Steps​

analyse​

Captures a screenshot, reads the Semantics and Focus trees, and runs all accessibility checks on the current screen. Creates a report entry.

steps:
  - analyse                     # report entry named after the screen
  - analyse "Login — filled"    # optional label for this capture

The label is optional. When omitted, the report entry uses the screen name. When provided, it becomes the entry name — useful when the same screen is captured in multiple states.

Place analyse wherever the screen is in the state you want to capture. Put it before navigation steps to capture the screen before leaving, or after a delay to let the screen finish loading first.

Screens without an analyse step are navigated through silently — no report entry is created.

tap​

Finds an element by its accessible label and taps it. Waits for the screen to settle after the tap.

steps:
  - tap "Sign in"

Use tap for any interaction that causes a visible screen change: navigation, opening a bottom sheet or dialog, toggling a switch, expanding an accordion.

note

If two elements share the same label, Conalyz taps the one that has an interactive action — duplicate interactive labels are themselves an accessibility violation.

TabBar tabs

Tab labels include position and total count when announced by TalkBack or VoiceOver. A tab titled Settings in a two-tab bar is announced as "Settings Tab 1 of 2" — use this full form. If you are unsure of the exact label, enable TalkBack (Android) or VoiceOver (iOS) to hear it announced, or let a tap fail — Conalyz will print all visible labels.

type​

Focuses a text field by label and types text into it.

steps:
  - type "user@example.com" into "Email"

Android — sends each character individually, 75 ms apart.
iOS — sends the full string at once. Special characters (@, ., etc.) are handled natively.

note

type focuses the field with a direct tap before typing. It does not check whether the screen changed after the focus tap — this is intentional, because gaining text field focus often leaves the screen visually unchanged.

back​

Navigates back one step in the navigation stack.

steps:
  - back
  - back "Close"    # iOS: use this label when the swipe-back gesture has no effect

Android — sends the hardware back key.
iOS — uses the standard iOS swipe-back gesture by default. Falls back to tapping the back button if the gesture has no effect (e.g. a modal without a swipe-back handler). Provide a label if your back button has a non-standard or non-English title.

scroll_to​

Scrolls the screen down until an element with the given label becomes visible, then stops. Use it before a tap when the target element is below the fold.

steps:
  - scroll_to "Submit"
  - tap "Submit"

If the label does not appear after scrolling through the full content, the step fails and the automated session stops for that screen.

tip

scroll_to is most useful on long forms or lists where the tap target may or may not be in view depending on the device screen size. It handles the scroll automatically so you do not need to know how far to scroll.

swipe​

Performs a horizontal swipe gesture — left or right. Use this for PageViews, carousels, and onboarding flows where content is arranged horizontally.

steps:
  - swipe left
  - swipe right

Works on both Android and iOS. The gesture is performed in the centre of the screen, which reliably lands in the content area for standard Flutter layouts.

Analysing each page of a PageView

Place an analyse step after each swipe to capture and check every page:

- screen: Onboarding
  steps:
    - analyse "Onboarding — page 1"
    - swipe left
    - analyse "Onboarding — page 2"
    - swipe left
    - analyse "Onboarding — page 3"

wait_for​

Waits until an element with the given label appears on screen, then continues. Use this instead of delay when a screen loads content from the network — wait_for proceeds as soon as the content is ready rather than waiting a fixed time.

steps:
  - wait_for "Dashboard"              # waits up to 10 seconds
  - wait_for "Dashboard" timeout 20s  # custom timeout
  - analyse

If the label does not appear within the timeout, the step fails and the automated session stops for that screen.

tip

Place wait_for before analyse on any screen that loads data after it appears:

- screen: Home
  steps:
    - wait_for "Recent Activity"   # wait for the list to load
    - analyse
    - tap "Settings"

delay​

Waits for a fixed number of seconds before the next step runs.

steps:
  - delay 2s
  - delay 1.5s    # decimals are supported

Place delay before analyse on a screen that loads data from the network — this way the wait is expressed on the screen that needs it, not on the previous one.

- screen: Violations Screen
  steps:
    - delay 2s      # this screen needs time to load
    - analyse
    - tap "Next"
tip

Prefer the smallest delay that reliably works in your environment. A delay that is too short captures a loading state; a delay that is too long slows down the full audit unnecessarily.

Multi-state captures​

Because analyse is just a step, you can capture the same screen in multiple states by placing analyse at each point you want a snapshot:

- screen: Dark Mode Toggle
  steps:
    - analyse "Dark Mode Toggle — light"   # report entry: light mode
    - tap "Dark Mode"                       # toggle — stays on same screen
    - analyse "Dark Mode Toggle — dark"    # report entry: dark mode
    - back

Each analyse creates a separate report entry. Use labels to distinguish the states — without them both entries would be named after the screen and look like duplicates in the report.

Full example​

flow:
  - screen: Login
    steps:
      - analyse
      - type "user@example.com" into "Email"
      - type "mypassword" into "Password"
      - tap "Sign in"
      - wait_for "Home"              # wait for navigation after login

  - screen: Home
    steps:
      - wait_for "Recent Activity"   # wait for data to load
      - analyse
      - tap "Account"

  - screen: Account Settings
    steps:
      - analyse
      - back

  - screen: Home (back)
    # no analyse — navigate through without capturing
    steps:
      - tap "Notifications"

  - screen: Notifications
    steps:
      - delay 2s     # fixed wait as a fallback if wait_for is not suitable
      - analyse

  - screen: Onboarding
    steps:
      - analyse "Onboarding — page 1"
      - swipe left
      - analyse "Onboarding — page 2"
      - swipe left
      - analyse "Onboarding — page 3"
      - back