Best practices

Keep tests small

One test checks one thing. Put each check in its own step so a failure directly relates to the check. A test with ten steps is easier to read and fix than a test with fifty.

Use stable selectors

Use el("<element id>"). Do not select by text, position, or Bubble's own classes. Text changes with copy edits. Classes change at runtime. Element ids do not change and Buildprint's test harness maps these at runtime.

Scope elements inside reusables and repeating groups (you need to decide which cell to select). If unscoped, buildprint check will warn you because the reusable or element might appear more than once.

One folder per feature

Put the tests for one feature in one folder: tests/agency/, tests/billing/. Run the folder while you work on that feature. Run --all before a release.

Own your data

Each run creates the data it needs in setup and removes it in teardown. Name test records with $BUILDPRINT_TEST_RUN_ID so runs do not collide and cleanup is exact. Set onFailure: "continue" on teardown steps so one failed cleanup does not hide the rest.

Do not depend on data another test created. Do not depend on data a human entered.

Use agent steps only when you must

An agent step will pause the run, take a screenshot, and require a decision from an agent. Use it for checks a command cannot make (e.g a chart looks right, a layout is not broken, or the AI chat response quality is good). Write the brief so an agent with no context can decide: one sentence for the task, where to look, and what pass and fail criteria look like

Run before you ship

Run the folder you changed after every buildprint apply. Run --all on the branch before you deploy it. The Dashboard shows the branch each run targeted.

Fix or delete flaky tests

Check the Dashboard regressions each day. A test that fails without a change in the app is 'flaky', meaning it breaks unreliably. Fix it or delete it, because if you have tests that just fail randomly then you'll start ignoring the test suite as a whole which takes away its utility.

Common causes of flaky steps:

• A hidden element clicked before it appeared. Add agent-browser wait <selector> first.

• A wait longer than the default. Pass --timeout <ms> to agent-browser wait and set timeoutMs a few seconds above it.

• Test data left over from a failed run. Make setup clear it, not only teardown.

• A generated name too long for a Bubble input. Keep it short: Test $(echo "$BUILDPRINT_TEST_RUN_ID" | cut -c1-12).