Sahi Script Best Practices
Rules for writing Sahi scripts that are reliable and easy to maintain, whether you write them yourself or an AI assistant writes them.
These rules make scripts reliable and easy to maintain. They are written so that people and AI assistants can both follow them. For organising whole suites and teams, see Best Practices in Using Sahi.
Finding elements
Section titled “Finding elements”- Identify elements by the text or label users see, for example
_link("Logout"), not by position or generated ids. - When the same text appears more than once, use a relation such as
_nearor_ininstead of an index like[2]. See Accessor Basics. - Use the Controller to pick accessors instead of writing them by hand.
Waiting
Section titled “Waiting”- Do not add fixed pauses. Sahi already waits for pages and AJAX requests to finish.
- When you must wait for something specific, use
_waitwith a condition and a time limit.
Checking results
Section titled “Checking results”- End every test with assertions that prove it passed, such as
_assertExistsor_assertEqual. See Assertion Functions. - Check one thing per assertion, so a failure tells you exactly what went wrong.
Structure
Section titled “Structure”- Put repeated steps in functions in a library file, and load it with
_include. - Keep test data out of the script. Read it from a file with the Data Drive Functions.
- Give functions and variables names that say what they do. Remember that variables start with
$.
Handling failures
Section titled “Handling failures”- Handle errors you expect and recover from them. See Exception Handling.
- Use the Logging Functions to add messages that explain what the script was doing when it failed.

