Skip to content
Get Free Trial

Sahi Controller

Record a keyword's steps, identify elements, try steps before you add them, and run your test case from the Controller.

The Controller is a small window that works alongside your browser. You use it to record a keyword’s steps, identify elements on the page, try a step before you add it, and run the test case.

Open the Controller from the keyword you want to record. It then knows where your steps belong: what you record goes into that keyword, and the browser starts at the right page.

From a keyword (the usual way):

  1. In the No-Code Test Editor, select the keyword and click Automate.
  2. In the Automate with Controller dialog, choose the browser and set Start URL. Check that Testcase / Global and Keyword show the ones you want.
  3. Click Launch Controller. The browser opens at the start URL, and the Controller opens on that keyword.
The Automate with Controller dialog with Google Chrome, the sample application URL, books.s.csv, Buy Books, Login and books.sah

From any page: in a browser opened by Sahi Pro, hold Alt (Option on Mac) and double-click the page. The Controller doesn’t know which keyword you’re working on, so it opens on a Draft Keyword. Steps you record there can be saved to a keyword file later.

The Controller has two tabs:

  • Automate: record, edit, save and run the keyword’s steps.
  • Advanced Editor: identify an element on the page and build one step for it.

At the top right are the mode the Controller works in (such as Browser, Java, Android or iOS), Minimize and Exit Controller. The bar at the bottom opens the Sahi Editor, Reports and the Clipboard, and ⋮ holds Diagnose, Controller Info and Help Docs.

Writing each step of a keyword by hand is slow, and it’s easy to get an element’s accessor wrong. Recording writes the steps for you: you use the application in the browser as a user would, and each action becomes a step with the right accessor.

  1. Open the Controller on the keyword.

  2. Click Record. The status changes from idle to Recording.

    The Controller on the Login keyword of Buy Books, with the Record button highlighted
  3. Work in the browser. Each action you take appears as a step in the Controller.

  4. Click Save. Steps not yet saved are marked with an orange dot, and the Save icon turns orange until you save.

    The Controller with three recorded Login steps not yet saved, shown by orange dots and an orange Save icon, which is highlighted

The Controller doesn’t save on its own, so save after you record or edit steps. Actions you take in the Controller itself aren’t recorded, only actions in the browser.

When a recorded step isn’t quite right, or the application changes, you don’t have to record the whole keyword again. Change just that step:

  1. Choose the keyword. Use the arrows next to it to go to the previous or next keyword.
  2. Click a step. It opens as Edit Step, where you can change its Action, Element and Value.
  3. Click Update.
  4. Click Save.
A step of the Add Books keyword open in Edit Step, with Action, Element and Value, and the Update button highlighted

To work on several steps at once, tick them. The toolbar above the steps then moves them up or down, disables or enables them, cuts, copies, pastes or deletes them, and undoes or redoes a change. To try selected steps on the page without running the whole keyword, click Evaluate Selected Steps.

The Add Books To Cart keyword in the Controller with its first two steps ticked and the step toolbar above them highlighted: move up, move down, disable, enable, cut, copy, paste, delete, undo and redo

A recorded keyword keeps the exact values you typed, such as one user name, so every run uses the same data. Parameterize turns those values into parameters, so each test case can pass its own data. The dialog lists the recorded values and the parameters it suggests for them. You can pass parameters as an object, give each one a Data Generator, and remove duplicates.

The Parameterize dialog for Register User, listing the recorded values john, the encrypted password twice and 12th main street, with the suggested parameters Username, Password, Password1 and Address

For a walkthrough, see Parameters and Data Generators.

Every step needs an accessor, which is how Sahi finds an element on the page, such as _textbox("user"). You identify an element in the Controller’s Advanced Editor to see its accessor, check that Sahi finds the one you mean, and turn it into a step.

Recording only captures what you do in the browser, so some steps can’t be recorded, such as a check that the total is 1550, or storing a value to use later. Build these in the Advanced Editor:

  1. Open the Advanced Editor tab.

  2. Hold Ctrl (⌘ on Mac) and hover over the element in the browser. Element Accessor shows its accessor.

  3. Under Quick Actions, choose what to do with the element, such as Click, Set Value, Store or Assert Equal. Other Actions has the rest.

  4. Enter a Value if the action needs one.

  5. Click Evaluate Step to try it on the page, then Add as Step. The step is added to the keyword. Discard clears it instead.

  6. Click Save in the Automate tab. Like recorded steps, it isn’t saved until you do.

The Advanced Editor with _textbox("user") identified, Set Value chosen with the value test, and Set Value and Add as Step highlighted

To check a value, choose Assert Equal and enter the expected value, as in Your First Test Scenario.

The top of the Advanced Editor with numbered controls: 1 Highlight, 2 Identify parent element, 3 Identify previous child element, 4 Visual Assist, 5 Session info, 6 View Element Properties, 7 Copy accessor to Evaluator, 8 Element Accessor, 9 Anchor, 10 Window or Domain Prefix
  1. Highlight: shows the element on the page.
  2. Identify parent element: moves to the element around it.
  3. Identify previous child element: moves back to the element inside.
  4. Visual Assist: turns on Visual Assist identification (see Visual Assist).
  5. Session info: shows the session the Controller works with.
  6. View Element Properties: opens the element’s properties and methods.
  7. Copy accessor to Evaluator: puts the accessor in the Evaluator.
  8. Element Accessor: the accessor for the element. Its list holds the alternatives.
  9. Anchor: identifies another element relative to this one.
  10. Window or Domain Prefix: for popups and pages from other domains.

For Windows applications, start the Desktop Engine first. See Start Windows Desktop Automation.

Some elements look the same to Sahi, such as the quantity box in each row of a table. Sahi then tells them apart by position (the third box), which breaks if the rows change. Anchor the element to a unique label next to it, such as the book’s title, instead:

  1. Hold Ctrl (⌘ on Mac) and hover over the element to anchor to, such as the text Python Cookbook.
  2. Click Anchor.
  3. Hold Ctrl (⌘ on Mac) and hover over the element you want. Its accessor is now relative to the anchor, for example _textbox("q", _near(_cell("Python Cookbook"))).
An animation of the three steps, with the browser above the Controller. The cursor hovers over Python Cookbook in the books table, and the Controller shows _cell("Python Cookbook"). It moves down and clicks Anchor in the Controller. It moves back up to the quantity box in the Python Cookbook row, and the Controller shows _textbox("q", _near(_cell("Python Cookbook"))).

Sometimes the check you need isn’t an element’s text or value but one of its properties, such as whether a field is disabled or how many characters it allows. Element Properties lists them all. Identify the element, then click View Element Properties, the third of the four icons at the top right of the Advanced Editor (6 in the picture above). The Properties tab lists the element’s properties and their values, and Methods lists what the element supports. Select properties and click Assert or Store to turn them into steps.

The Element Properties dialog for _textbox("user") on the Properties tab, listing form, formAction, maxLength, minLength, name and size, with Assert, Store, Create Element and Done

Some elements can’t be found from the page’s code, such as a button that’s only an image, or text inside a picture. Visual Assist finds them by how they look instead. It needs the Visual Assist Engine.

  1. In the Advanced Editor, click Visual Assist (4 in the picture above). The Visual Assist panel appears.

  2. Choose how to find the element: Image Recognition finds it by its picture, and Optical Character Recognition finds it by its text.

    The Advanced Editor with Visual Assist turned on and its list open, showing None, Image Recognition and Optical Character Recognition, with the Visual Assist button and the list highlighted
  3. For Image Recognition, click Capture an image to identify to capture the image to look for. The number beside it delays the capture by that many seconds, so you can bring the right window to the front first. Open the images directory shows the images you’ve captured.

    The Visual Assist panel with Image Recognition chosen, the capture delay 0, and the Capture an image to identify button highlighted

For a walkthrough, see Visual Assist Automation - Getting Started.

When a step fails, it’s hard to tell whether the accessor is wrong or the page isn’t ready yet. The Evaluator runs a piece of Sahi code on the page straight away and shows the result, so you can test an idea without running the whole test.

  1. In the Advanced Editor, click Open Evaluator, and select Show Script.
  2. Type the code, for example _exists(_textbox("user")).
  3. Choose the mode, then click Evaluate. The result appears below.

The mode is the kind of application the code runs against, such as Browser, Windows or Java. Choose JS to run plain JavaScript instead of Sahi code.

To run only part of the code, select it before you click Evaluate. The box can hold several statements, so you can keep a few checks there and run one at a time.

The Evaluator with _exists(_textbox("user")) and the result true, with the Evaluate button highlighted
  • Search API List: start typing a function name and press Enter. The function is added with its parameters.

  • Action: select part of the code, such as an accessor, and choose an action for it, such as Get Value, Get Text, Exists or Is Visible. The result shows for just that part.

    The Evaluator with _textbox("user") selected in the code and the Action button highlighted, its list open below it, showing Click, Get Value, Get ARValue, Get Text, Get toJSON, Exists and Is Visible
  • Highlight shows the element in the code on the page.

  • History lists your recent recording actions.

  • x,y: select it, then hold Ctrl+Shift (⌘+Shift on Mac) and move the mouse over the page to see the point’s clientX and clientY.

Hover over Run to run the keyword, part of the test case or all of it, and use Pause, Play, Step and Stop while it runs. See Run Tests via Controller.

When an element on the page changes, every script that uses its accessor stops finding it, and you’d have to fix each one. An Accessor Repository (AR) keeps accessors in one place, so you update an accessor once and every script that uses it gets the change. An AR is a Sahi script whose name ends in _AR.sah.

  1. In the Automate tab, click File Settings.

  2. Turn on Enable AR, and choose the file under Accessor Repo.

    The Controller with the File Settings panel open at the bottom, showing Script Directory, Scenario File, Keyword Repo and Accessor Repo, with the Enable AR switch highlighted

With AR on, the Advanced Editor shows an Accessor Name for the element, and Update in AR saves its accessor to the repository.

Once an element is in the AR, Sahi identifies it by its AR entry first, even when you aren’t recording. So the same element isn’t identified in different ways in different tests, and an element someone already anchored, for example with _near, keeps that accessor for everyone.

File Settings also shows the script directory, the scenario file and the keyword repository the Controller records into. You can’t change them while recording.

The script directories come from scripts.dir in userdata/config/userdata.properties, one per project, separated by semicolons. Relative paths are relative to the userdata directory:

scripts.dir=scripts;D:\my_custom_folder
  • Clipboard in the bottom bar keeps small pieces of text while you work.
  • Controller Info in the ⋮ menu shows the versions of Sahi Pro and its engines, the Controller mode, and details of the browser, operating system and Java.