A Dev Scenario flow looks like a list of plain commands. Under that list is a real, if very small, programming language with its own lexer, parser and tokens. It does one job: describe what a person does in a mobile app, and check what they see.
Here's a flow:
launchApp("com.shop.app", clearState = true)
// Shared steps, written once as a function
common.openHomeScreen(userName = @username)
// Variables and conditions
val total = numberOf(id("total"))
if (total > 100 && visible("Free shipping")) {
tap("Apply")
}
// A loop over what's on screen, found with a regex
forEach(regex("^Order #.*")) {
tap("${item.text}")
assertVisible("Paid")
back
}
// Files the app wrote
assertThat(read("screens.log").lastLine() == "Orders")
You can read that without knowing the language, and that's the point. It has commands that read like instructions, plus variables, functions, loops, if statements, regex and working with files. The command reference has all of it.
This post is about what happens between that text and a tap on a phone. If you've never heard of a lexer, that's fine. You don't need any of this to write a flow, but it explains why the tooling around flows can be so helpful.
How a computer reads a language
To a computer, a program is one long string of characters. It doesn't see commands or lines of logic, only t, a, p, (. Making sense of that happens in stages, and it works much like the way you read a sentence:
| Stage | What it does | In the sentence "Tap Login within ten seconds" |
|---|---|---|
| Lexer | Splits the characters into tokens: the words and punctuation of the language | Spotting the separate words |
| Parser | Checks the grammar and arranges the tokens into a structure, usually a tree | "Tap" is the action, "Login" is what to tap, the rest is a limit |
| Checks | Asks whether it makes sense. Good grammar can still mean nothing | "Tap Login within ten bananas" fails here |
| Interpreter | Does what the program says | Actually tapping Login |
Kotlin, Swift and Python all go through the same basic stages. Some add a compiler, which translates the program into a lower-level form before it runs. A flow doesn't need that: the engine runs its commands directly.
The same stages, for one line of a flow
Follow this line through them:
tap("Login", timeout = 10s)
The lexer produces these eight tokens, plus an end-of-line and an end-of-file marker:
| Written | Token | Value |
|---|---|---|
tap | IDENT | tap |
( | LPAREN | ( |
"Login" | STRING | Login, without the quotes |
, | COMMA | , |
timeout | IDENT | timeout |
= | ASSIGN | = |
10s | DURATION | 10000 milliseconds |
) | RPAREN | ) |
Look at 10s. A duration is a type of word in this language, like a string or a number. So is a percent such as 50%, and a test-data reference such as @username. In a general-purpose language those would be a library call or a string. Here they're part of the alphabet, because mobile tests need them all the time. There are 18 kinds of token in total.
The parser takes those tokens and builds a tree. It's easier to see on the condition from the first example, which has to know that > happens before &&:
if
├─ condition: &&
│ ├─ > total, 100
│ └─ visible("Free shipping")
└─ body
└─ tap("Apply")
That tree is called an abstract syntax tree, or AST. "Abstract" because it has dropped the things that were only there for writing: spaces, brackets, line breaks. Indentation means nothing in a flow, since only the tree counts.
Lowering turns the tree into the engine's commands, and this is where sense gets checked. Is there a command called tap? Does it have an option called timeout? Compilers use the word "lowering" for moving from a form made for people to one made for machines.
The engine is the interpreter. It runs the commands one by one through a driver: the in-app SDK, UIAutomator on Android or the XCUITest runner on iOS. The language doesn't care which, so the same flow runs on both platforms.
What all of this gives you
A list of commands could be kept in a data format, and ours once was: flows used to be YAML-like files. But a data format can't see inside its own values. It knows a key has a string. It doesn't know that the string is a condition with a typo in it. Once a flow is tokens and a tree, tools can understand it, and most of what you touch every day comes from there.
Autocomplete that knows where you are
The editor reads the flow again on every edit, then uses the tokens to work out what your cursor is inside of. Typing a new line, it offers commands. Inside tap(, that command's options. After ., what can be chained. After @, the keys in your param profiles. After $ in a string, your variables. It's the difference between suggesting words and suggesting what fits here.
Errors in your language
Because every token remembers its position, a mistake gets marked on the statement it belongs to, while you type. These are real messages:
waitFor("Login", timout = 10s)
waitFor has no option 'timout'. Its options: timeout, optional, retryOnFail
tap("Login"
tap( is not closed
For a misspelt command or option, the editor offers the fix. And it doesn't stop at the first mistake. When a statement is broken, the parser notes the error, skips to the next statement and carries on, so a mistake in one part of the flow doesn't hide mistakes further down. Inside a block such as if or forEach, you see the first refused command, then the next once it's fixed.
Advice about your test, not only your syntax
A language that knows what a flow means can also spot things that are valid but costly. How you write a flow is up to you, so the editor only shows errors. But when an AI agent writes a flow over MCP, it gets warnings too, and the save is refused until it fixes them or gives a reason. wait(2s) is correct code, and the agent still hears:
wait(2s)
Fixed sleep of 2.0 s, paid on every run. Wait for what comes next instead
(waitFor, waitUntilGone or waitForIdle).
Variables and values
Values are part of the language. That's why val total = numberOf(…) can be used in a condition, in an assertion or inside a string as "Total is $total".
Functions
The first example starts with common.openHomeScreen(…). That's a function you write yourself, once, in a unit of its own:
scope(common)
// Logs in and waits for the home screen.
fun openHomeScreen(userName: String, password: String = @password) {
type(userName, into = "Email")
type(password, into = "Password")
tap("Login")
waitFor("Home")
}
scope(common) groups the unit's functions under a name you pick, so two teams can both have a login. Parameters have a type, String, Number, Boolean or Duration, and can have a default. Arguments are always named, so a call reads the same as a command.
A call doesn't need a new kind of engine. Before a flow runs, each call is replaced by its function's steps, with the arguments put in place of the parameters. Everything after that, from lowering to the engine, sees ordinary .ds, so a function works in the app, the CLI and on CI alike. Reports still point at the line of the call, and the @password default reads the profile the calling flow uses.
Because a call has to match its function, the checks catch the mistakes early:
common.openHomeScreen(usrName = @username)
common.openHomeScreen has no parameter usrName; it takes userName, password
common.openHomeScreen()
common.openHomeScreen needs userName (String)
A wrong type, an unknown function and a function that ends up calling itself are refused the same way. In the editor, typing common. lists the scope's functions, Cmd/Ctrl-click on a call opens its function, and Alt+F7 shows every unit that calls it.
One source of truth
Commands and their options live in one catalog: 75 commands and 21 selector functions. Autocomplete, the command reference and the tools AI agents get over MCP read from it, and tests keep the parser in step with it. And the same parser runs in the app, in the CLI and on CI, so a flow means the same thing wherever it runs.
Not a general-purpose language, on purpose
You won't find classes, while loops or a standard library in .ds. A flow's steps are of four kinds: a command, a variable assignment, an if and a call to a function. Functions are there to share steps, not to build programs: they hold the same statements as any flow, and can't call themselves.
A narrow language buys things a general one can't offer:
- Less to learn. Someone who has never programmed can read a flow on day one and write one soon after.
- The mobile world is built in. "The Delete button below Item 3" is
tap("Delete").below("Item 3"). Waiting, durations, platforms and permissions are part of the language, not a library to import. - One way to write each thing. When two commands did nearly the same job, we merged them. Checking for part of a text isn't a command of its own, just
assertVisible(contains("…")). Fewer ways to write a step means flows from different people look alike. - Tools can trust it. A small language is easy to analyze, and easy to generate. Record mode writes
.ds, and so do AI agents.
How a command gets in
In a language this small, each command counts, and removing one later is painful for everyone who used it. So we go through the same questions each time, before and while building it:
Is it useful?
Does it come from a test someone really needs to write? Can an option on an existing command do it instead? Often the answer to the second question is yes, and then there's no new command.
Is it easy to use?
Does the line read like what it does? Are the name and options obvious without the docs? Would someone reviewing a flow understand it?
Is it fast?
Test suites live or die on speed, so we measure. Runs on the in-app SDK must not get slower, and we compare before and after on the same device boot. It shapes the design too: if (visible("Allow")) looks once and moves on, so a missing dialog costs one look, not a timeout.
Does it work on both platforms?
A flow should run on Android and iOS. Where a platform or driver can't do something, the reference says so in the command's limits, so you find out before you depend on it.
Is it complete everywhere?
A command isn't done until it has autocomplete, a docs page with examples, tests, and can be written back as .ds for record mode. Automated checks compare the options the parser reads with the catalog, and CI rejects a site page that shows a command the parser would refuse.
Where you come in
This structure is why the language can keep growing without getting messier. A new feature isn't a hack on top of a file format. It has a place in lowering and the catalog, and checks notice when the docs or the catalog fall behind. Reading the app's files, date functions like day() and functions you write yourself were all added this way.
So the most useful thing we don't have is your flows. What's hard to express today? What do you write as five steps that should be one? Which check can't you write at all? Tell us on the roadmap: request a feature, vote on the ones you'd use, and see what's planned. Requests with real tests behind them are what shape the language next, and they go through the same questions as every other command.