# Sahi Pro Documentation (full text) --- # Welcome to Sahi Pro Automate functional tests of web, Rest API, mobile, Windows desktop, Java and SAP GUI applications, all from one platform. :::tip[Sahi Pro v12.0.0.10 is here] See [what's new in Sahi Pro v12.0.0.10](https://resources.sahipro.com/docs/release-notes/v12-0-0-10/). ::: Sahi Pro is a mature, business-ready test automation platform for UI-heavy applications. Built on 20 years of automating complex enterprise applications, it lets anyone on your team build reliable tests without code. Sahi waits for pages and retries steps on its own, so tests are quick to build, easy to maintain and reliable to run.
Build tests in the No-Code Test Editor by putting together keywords named after the steps of your business process, such as Login or Create Order. Like well-written code, each part of a test has its own place, so tests stay easy to modify and maintain in the long run, which is 90% of the work in test automation.
In many teams, automation can only start once the application is ready, so tests fall behind every release. Sahi Pro is built for Business-Driven Test Automation (BDTA): you write a test in the language of the business first, and automate its steps when the application is ready. Most of the work happens before the application is built.
Before the application exists, you can:
When the application is ready, record each keyword's steps in the Controller, or let AI Suggest author the keyword for you.
For web applications, Sahi automatically waits for pages to load and for data that loads in the background. Further, on failure, Sahi automatically retries the step a few times. In 95% of cases there is no need to add wait steps. This cuts the number of steps in a test by 50% compared to other tools, and keeps tests robust yet easy to maintain. Similar mechanisms used for mobile, desktop, Java and SAP.
A Controller for the age of AI. With AI Suggest, the Controller reads the page and authors the keyword for you, so you don't have to fill in each step by hand. Build tests the same way for every kind of application: the Controller and object spy work on Chrome, Firefox, Internet Explorer, Safari, Opera (and any modern browser), Mobile (iOS, Android) and Desktop applications (Windows, Java etc.).
One web-based editor for the whole team. Subject matter experts can view scenarios to check that they match the business, testers can write scenarios and tests, and engineers can work on keywords in code. Intelligent auto suggestions and refactoring make tests easy to modify and maintain. A Rest API editor is built in for working with Rest APIs and Web Services.
In large companies, one business process often crosses several applications: an order starts in a web portal, is processed in a Windows desktop application and is approved on a mobile app. Sahi Pro stitches these together, so one test covers the whole flow without switching tools.
Enterprise applications always have complex, domain-specific scenarios that no-code alone can't cover. Sahi Pro has handled them for enterprises for years, and Sahi Script is always there as an escape hatch: no-code handles most of the work, and code handles the rest.
Enterprises want AI in their testing without sending their data outside. Sahi Pro Atlas supports Bring Your Own Key (BYOK), so it works within your security rules.
Enterprises need test evidence they can review, share and keep for audits. Sahi Pro saves detailed reports as offline files, with every step, error and screenshot of a run.
A full regression run can mean thousands of tests, each with its own data and its own place in the order. Data-driven suites (.dd.csv files) list them all in one sheet and run them as a single batch.
A large suite can take hours when its tests run one after another. Sahi runs tests in parallel on one machine and across many machines, so the same suite run finishes in a fraction of the time.
When a suite run fails, you need to see quickly what broke and why. Sahi creates a detailed report for every run automatically and keeps it, so you can go from a summary of all runs down to the exact failing step.
| Technology | WebEngine | DesktopEngine | MobileEngine | SAPEngine |
|---|---|---|---|---|
| Data and services | ||||
| Database | Supported | Supported | Supported | Supported |
| Filesystem | Supported | Supported | Supported | Supported |
| Rest APIs and web servicesOAuth2 needs the Web Engine. | Supported | SupportedNo OAuth2 | SupportedNo OAuth2 | SupportedNo OAuth2 |
| Web | ||||
| Web applicationsAcross browsers and operating systems | Supported | Not supported | Not supported | Not supported |
| Web applications on mobile browsersNeeds the Web and Mobile Engines together. | SupportedTriggered from the device | Not supported | Not supported | Not supported |
| Chromium Embedded Framework (CEF) applications | Supported | Not supported | Not supported | Not supported |
| Flex applicationsSDK 3.4 onwards | Supported | Not supported | Not supported | Not supported |
| Desktop | ||||
| Windows desktop applicationsWPF, Win32, WinForms, .NET, SilverLight, XBAP and other applications targeting .NET Framework 2.0 onwards; applications built with the Microsoft Foundation Class library | Not supported | Supported | Not supported | Not supported |
| Java applicationsSwing, AWT and SWT, Java 1.8 onwards | Not supported | Supported | Not supported | Not supported |
| Java Web Start applicationsSwing, AWT and SWT, Java 1.8 onwards | Not supported | Supported | Not supported | Not supported |
| Java appletsSwing, AWT and SWT, Java 1.8 onwardsDetails | Not supported | Supported | Not supported | Not supported |
| Oracle Forms12.x onwardsDetails | Not supported | Supported | Not supported | Not supported |
| Mobile | ||||
| Native apps on iOS and AndroidAndroid SDK 18 onwards (Android 4.3.x onwards); iOS 9.3 onwards with Xcode 9.2 onwards | Not supported | Not supported | Supported | Not supported |
| Hybrid apps on iOS | Not supported | Not supported | Supported | Not supported |
| Hybrid apps on AndroidNeeds the Web and Mobile Engines together. | Not supported | Not supported | PartlySome apps are identified natively | Not supported |
| SAP | ||||
| SAP GUI for Windows6.2 onwards | Not supported | Not supported | Not supported | Supported |
## Quick Start
- [Automating Windows Desktop Applications](https://resources.sahipro.com/docs/using-sahi/windows-desktop/)
- [Automating Java GUI Applications](https://resources.sahipro.com/docs/using-sahi/java-application/)
- [Automating Java Web Start Applications](https://resources.sahipro.com/docs/using-sahi/javaws/)
- [Automating Java Applets](https://resources.sahipro.com/docs/using-sahi/applet-new/)
## Sahi Pro Desktop Engine Runner
Sahi Pro Desktop Engine can also be installed over Sahi Pro Runner, which runs tests but doesn't author them.
## Version Information
Sahi Pro Desktop Engine was introduced in Sahi Pro 7.0.0.
---
# Sahi Pro Mobile Engine
Sahi Pro Mobile Engine adds automation of Android and iOS applications to Sahi Pro.
Many business flows end on a phone: an approval, a notification, a field update. Mobile Engine automates native Android and iOS apps alongside your web tests.
:::caution[Important]
Install Sahi Pro first, then install Mobile Engine in the same directory.
:::
## Features
- Automation of Android applications
- Automation of iOS applications
- Run multiple tests in parallel
- Distribute the tests in a suite across multiple machines
## License
Mobile Engine needs its own license, separate from Sahi Pro. For a 14-day free trial, [book a demo](https://sahipro.com/get-started/) and we'll set up your trial, or email sales@sahipro.com.
## Quick Start
1. [Download and Install Sahi Pro Mobile Engine](https://resources.sahipro.com/docs/using-sahi/mobile-engine/)
2. [Get started with Android Automation](https://resources.sahipro.com/docs/using-sahi/android-getting-started/)
3. [Get started with iOS Automation](https://resources.sahipro.com/docs/using-sahi/ios-getting-started/)
## Sahi Pro Mobile Engine Runner
Sahi Pro Mobile Engine can also be installed over Sahi Pro Runner, which runs tests but doesn't author them.
## Version Information
Sahi Pro Mobile Engine was introduced in Sahi Pro 7.5.0.
---
# Sahi Pro SAP Engine
Sahi Pro SAP Engine adds automation of SAP GUI for Windows to Sahi Pro.
Many enterprises run core business processes in SAP GUI, and testing them by hand is slow and error-prone. SAP Engine automates SAP GUI for Windows alongside your web and desktop tests.
:::caution[Important]
Install Sahi Pro first, then install SAP Engine in the same directory.
:::
## Features
- Automation of SAP GUI for Windows, version 6.20 and later
- Run multiple tests in parallel
- Distribute the tests in a suite across multiple machines
## License
SAP Engine needs its own license, separate from Sahi Pro. For a 14-day free trial, [book a demo](https://sahipro.com/get-started/) and we'll set up your trial, or email sales@sahipro.com.
## Prerequisites
1. Java 1.8 or above is needed for running Sahi Pro.
2. Microsoft Visual C++ Redistributable 2008 x86 or Microsoft Visual C++ Redistributable 2010 x86. Verify the installed version of Microsoft Visual C++ Redistributable as follows:
- Open Add and Remove Programs and look for Microsoft Visual C++ Redistributable.
- The installed versions will be listed there.
3. Microsoft .NET framework v4.5+. Verify the installed version of Microsoft .NET framework as follows:
- On the Start menu, choose Run.
- In the Open box, enter `regedit.exe`
- In the Registry Editor, open the following subkey: `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full`
4. SAP GUI scripting interface must be installed. Also, scripting must be enabled for SAP GUI client and server both. To enable it, see [Start SAP GUI Automation](https://resources.sahipro.com/docs/using-sahi/sap-gui-getting-started/#start-sap-gui-automation).
## Quick Start
- [Getting Started with SAP GUI Automation](https://resources.sahipro.com/docs/using-sahi/sap-gui-getting-started/)
## Sahi Pro SAP Engine Runner
Sahi Pro SAP Engine can also be installed over Sahi Pro Runner, which runs tests but doesn't author them.
## Version Information
Sahi Pro SAP Engine was introduced in Sahi Pro 9.0.0.
---
# Sahi Pro Visual Assist Engine
Sahi Pro Visual Assist Engine uses computer vision and machine learning to add Image Recognition and Optical Character Recognition (OCR) to the Web, Desktop and Mobile Engines.
Some elements can't be identified through the application's structure, especially in complex BFSI or B2B applications and edge cases. Visual Assist Engine identifies them by how they look and the text they show.
:::caution[Important]
Install Sahi Pro first, then install Visual Assist Engine in the same directory.
:::
## Features
- **Image Recognition:** identify an element by its image on screen.
- **Optical Character Recognition (OCR):** identify an element by the text it shows on screen.
## License
Visual Assist Engine needs its own license, separate from Sahi Pro. For a 14-day free trial, [book a demo](https://sahipro.com/get-started/) and we'll set up your trial, or email sales@sahipro.com.
## Prerequisites
- Java 8 Update 361 or above is required.
## Quick Start
To automate your first test with Visual Assist, see [Visual Assist Automation – Getting Started](https://resources.sahipro.com/docs/using-sahi/visual-assist-getting-started/).
## Sahi Pro Visual Assist Engine Runner
Sahi Pro Visual Assist Engine can also be installed over Sahi Pro Runner, which runs tests but doesn't author them.
---
# Sahi Pro Runner
Sahi Pro Runner is a lean version of Sahi Pro that only runs tests, built for CI servers and automated builds.
Sahi Pro Runner is recommended for [Continuous Integration (CI)](https://resources.sahipro.com/docs/using-sahi/integrate-with-jenkins/) and build systems, as the master or as a node, and as a [central database](https://resources.sahipro.com/docs/using-sahi/sahi-syncdb/) for reports.
On a CI server or build machine, you only need to run tests, not author them. Runner has no Controller or Editor, and a limited Dashboard.
Each concurrent license includes two free Sahi Pro Runner licenses, and you can buy more. For example, 5 concurrent licenses come with 1 product key that runs up to 10 instances of Sahi Pro Runner.
:::note
A user license can't run Sahi Pro Runner. You need a concurrent license.
:::
With a concurrent license, you can [download](https://resources.sahipro.com/docs/introduction/installers/) Sahi Pro Runner and use it on multiple machines.
:::caution[Important]
You can't launch browsers from the Runner Dashboard. It shows the available browsers as disabled buttons.
:::
## Engines on Sahi Pro Runner
There is no separate Runner version of the Engines. Install them over Sahi Pro Runner, and it runs their tests too:
- Sahi Pro Desktop Engine
- Sahi Pro Mobile Engine
- Sahi Pro SAP Engine
- Sahi Pro Visual Assist Engine
---
# Sahi License Hub
Sahi License Hub is where your organization views its Sahi Pro product keys, manages leases and MAC addresses, and controls who can get a license.
Every organization that buys Sahi Pro gets a Sahi License Hub login, where admins see all their product keys and share them with the team. If you haven't received yours, email sales@sahipro.com.
Anyone who installs Sahi Pro enters a product key the first time they start it. They get the key from their admin, who shares it from License Hub. Sahi Pro then checks the key with License Hub: a user license is matched to the machine's MAC address, and a concurrent license takes one of the available leases.
Product keys can be of two types: User or Concurrent.
- **User license:** tied to one machine, with a unique key for each user. It can't run Sahi Pro Runner.
- **Concurrent license:** not tied to a machine, but only a fixed number of people can use it at the same time. A team usually shares one key, and each concurrent license includes two free Sahi Pro Runner licenses.
## Manage Product Keys
When logged into the License Hub, the admin can see
1. All product keys (future, current and expired keys)
2. Leases against each product key
3. Usage report for each product key
For concurrent licenses, the admin can see all leases and revoke any lease if needed (in case any machine has crashed).\
For user licenses, the admin can bind it to another MAC address if the end user's machine has changed.
## Access Sahi License Hub Web Interface
1. Open [Sahi License Hub](https://license.sahipro.com/login.jsp).
You will need a registered email and password to sign in to Sahi License Hub. If you do not have any registered email or password yet, you can contact us at sales@sahipro.com for any query related to Sahi License Hub.
2. After a successful login user will get a list of licenses with all its details.
3. A user can perform the following actions: [Change MAC Address](https://resources.sahipro.com/docs/introduction/sahi-license-hub/#change-mac-address), [Manage Leases](https://resources.sahipro.com/docs/introduction/sahi-license-hub/#manage-leases), [License Usage Report](https://resources.sahipro.com/docs/introduction/sahi-license-hub/#view-license-usage-reports) or [Manage Access List](https://resources.sahipro.com/docs/introduction/sahi-license-hub/#manage-access-list).
## Change MAC Address
For User Licenses, a user's registered MAC address can be changed.
To check the system's MAC address from the command line:
1. Open a command prompt and cd to `Sahi/userdata/bin`(or click on the "Bin" link on the Sahi Dashboard).
2. Run `license_util.bat` or `license_util.sh` to see the MAC address.
Now you can use this MAC address in Sahi License Hub.
:::note
A user license runs only one Sahi Pro at a time.
:::
## Manage Leases
This link will bring up a page that lists all the Product Keys.
To view Lease details, click on `View Details` under Action column.
## View License Usage Reports
This shows the Sahi Pro License Usage Reports in graphical and tabular format.
### Graphical Representation
- The first graph shows the monthly usage of licenses as per the selected month. Month can be selected from Date Picker or clicking on the month shown in the left panel. By default, it displays reports for the current date.
- `Distinct` and `Concurrent` Users:
Suppose users A & B worked in the morning and users C, D, & E worked in the afternoon. So total distinct users are 5. But maximum of 3 users have concurrently used licenses, so total concurrent users are 3. This will help you understand your usage pattern and plan how many licenses to buy.
**Light Blue colored bar:** Displays distinct users count. **Dark Blue colored bar:** Displays concurrent users count.
- The second graph shows the daily usage of license data as per the selected date. Date can be selected from Date Picker or clicking on the Light/Dark blue colored bar shown in the first graph.
### Show Data
- This shows the Sahi Pro Usage and Sahi Pro License Denied List in tabular format.
- **Sahi Pro Usage List:** This will show the list of Sahi Pro users who got a license from Sahi License Hub successfully.
- **Sahi Pro License Denied List:** This will show the list of Sahi Pro users who were unable to get a license from Sahi License Hub.
- The image below shows the list of Sahi Pro users who got a license from Sahi License Hub successfully.
:::note
By default, user's details like IP address, Host Name, OS Name are stored in Sahi License Hub for your convenience. If you wish to avoid storing these details, the check box shown in the above image can be unchecked.
:::
- Possible errors while getting a license from Sahi License Hub:
```text
4001 - Invalid product key.
4002 - User is not allowed to access product key.
4003 - Issued product key will start from future dates.
4004 - Product Key Expired.
4005 - Product key is not issued for all the Sahi products.
4006 - Please use product key from registered mac address.
4008 - Could not obtain lease. All leases are issued.
4009 - User license can not use Sahi Pro Runner.
4010 - Time difference between the License Hub and the System is more than the allowed time difference.
```
- Sahi Pro Usage List and Sahi Pro License Denied List can be downloaded in CSV format by clicking on `Download CSV` link.
## Manage Access List
Access Control Lists help restrict access based on username, IP address or Mac address of the machine requesting license.
- Sahi Pro users who are added in the `Access Control List` can only access the Sahi License Hub and get a license.
- Adding Sahi Pro users to access list:
- **Set Access Type:** Select either `none` or `System's logged in username` or `IP Address` or `MAC Address`.
- `none` : No access type is set. Everyone will be allowed to get a license.
- `System's logged in username` : Username of the logged in system where Sahi Pro is installed.
- `IP Address` : IP Address of the logged in system where Sahi Pro is installed.
- `MAC Address` : MAC Address of the logged in system where Sahi Pro is installed.
- **Access Credentials:** Set the value based on the Access Type selected above (**Example:** `System's logged in username:` sahi, `IP Address:` 192.168.1.1, `MAC Address:` 00-0C-29-CC-11-10)
**NOTE:** Access Credentials value can be a regex pattern also.
Wildcard \* and ? can be used. \* matches any sequence of characters, whereas ? matches any single character.
**Example 1:** If the **Access Type** is `IP Address` and **Access Value** is `192.168.1.*` Then all the Sahi Pro users whose `IP Address` is from `192.168.1.0` to `192.168.1.255` can access Sahi License Hub and get the license.
**Example 2:** If the **Access Type** is `IP Address` and **Access Value** is `192.168.1.?` Then all the Sahi Pro users whose `IP Address` is from `192.168.1.0` to `192.168.1.9` can access Sahi License Hub and get the license.
- **Access Control List:** Lists all the added Sahi Pro users based on the selected Access type.
`Remove:` Click to remove the access for that particular Sahi Pro user.
## Version Information
Sahi License Hub was introduced in Sahi Pro 8.0.0. Sahi Pro 8.0.0 and later versions work only with licenses from Sahi License Hub.
---
# Architecture
The design goals behind Sahi, and how its architecture meets them.
## User Goals
Testing has two parts: the exploratory work that needs a tester's judgment, and the repetitive checking and rechecking of what already works. Sahi automates the repetitive part, so testers spend their time where judgment matters. That sets three goals:
1. **Testers can automate without being developers.** Building and maintaining a test shouldn't need programming skills. Code should be an option for the cases that need it, not a requirement.
2. **Tests describe the business flow, not the plumbing.** A test should hold only the steps and checks that matter to the business. Waiting for pages, handling frames and popups, and finding elements should be the tool's job.
3. **Running and reporting at scale are part of the tool.** Running large suites, in parallel and across machines, and reporting the results shouldn't need a separate framework built around the tool.
## Technical Goals
### Handling New Browsers and Operating Systems
Testing web applications on browsers can be painful. There are a multitude of browsers on different operating systems and each one has its own quirks. The tool should take care of these differences. Browsers are also available on mobile devices, but mobile devices may not be able to install and run full testing tools.
So the tool should:
- Work the same way on any browser and operating system
- Work on mobile browsers without installing anything on the device
- Support new browsers and new browser versions without changes to tests, and with minimal changes to the tool
:::note
Sahi works through a proxy that injects JavaScript into each page, and that JavaScript records and runs tests. To use any browser with Sahi, set its proxy to Sahi (localhost:9999). Every browser supports proxies and JavaScript and keeps them backward compatible, so Sahi works with any browser that runs JavaScript and lets you set a proxy.
:::
### Object Identification
Existing methodologies of using IDs, XPaths and CSS Selectors have proven to be woefully brittle and complex. When a test breaks, the first suspect is normally the test and how it identifies elements rather than the actual application. This adds a lot of waste into the testing cycle.
So the tool should:
- Identify elements in an easy way, and record them automatically as the user works with the application
- Avoid libraries like jQuery, which the application under test may also use and conflict with
- Use identifiers that relate to what the user sees on screen
- Use identifiers that work across browsers
:::note
Sahi uses its own wrappers around the JavaScript DOM to find elements. Its built-in functions read an element's DOM attributes, for example a button's value, name, id, CSS class or index. Relational functions like _near, _in, _under, _leftOf and _rightOf find one element by where it sits relative to another. All of them work the same way across browsers.
:::
### Event Simulation
- Event simulation should simulate the end user actions correctly across browsers.
- Should not need browser to be in focus, to allow parallel test runs and reduce brittleness of tests
- Should not force users to do implicit actions like scrolling into view.
:::note
Sahi predominantly uses JavaScript based events to simulate user actions. These work in 95% of cases. In some very special cases, where JavaScript events are ineffective, Sahi falls back on native events. Sahi tries to keep native events to a minimum since the browser needs focus in these cases. Needing focus leads to brittle tests and prevents parallel test runs.
:::
### Scripting
Most tests shouldn't need code. When a test does need custom logic, the scripting language should be one the team already knows.
- JavaScript is common to all web projects no matter what the back end technology may be. Using JavaScript as the scripting language makes sure that expertise is always available in a web team.
- Reporting should be taken care of automatically
- Scripting should allow easy reuse of existing libraries to do non-browser tasks
:::note
Sahi Script, the default language used by Sahi, is an extension of JavaScript. Sahi Script uses the same constructs of JavaScript, but adds capability to interact with the browser efficiently, and also perform system actions like read from file system, access database, call Java etc.
:::
### Agile
- Tests should be version-controllable and easy to compare
- Tests should break minimally when user interface changes
- Suites should allow being triggered from build and Continuous Integration systems
:::note
Sahi tests are plain text files which can be version controlled, and Git support is built in. Sahi's built-in functions are robust and can withstand peripheral UI changes. Sahi suites can be triggered from Ant, batch files, shell scripts, from Java code or just as simple URL calls.
:::
## Architecture
Sahi uses a proxy to inject JavaScript into web pages.
The injected JavaScript
- adds event handlers for recording
- adds Sahi's built-in functions for event simulation
- mocks some window dialogs like alert, prompt, confirm, print so that test runs aren't interrupted
---
# Sahi Script
What Sahi Script is, what a script looks like, and how Sahi runs it.
Sahi Script is Sahi Pro's scripting language, for the complex, domain-specific scenarios that no-code can't cover. It has the same syntax as JavaScript, except that variables start with a `$` sign.
## A Sample Script
A login-and-checkout test in Sahi Script:
**sample.sah**
```js
_setValue(_textbox("user"), "test");
_setValue(_password("password"), "secret");
_click(_submit("Login"));
_setValue(_textbox("q"), "2");
_setValue(_textbox("q[1]"), "1");
_setValue(_textbox("q[2]"), "1");
_click(_button("Add"));
_click(_cell("Rs.200[1]"));
_assertExists(_textbox("total"));
_assert(_isVisible(_textbox("total")));
_assertEqual("1150", _textbox("total").value);
_click(_button("Logout"));
```
The same test, split into a test file and a library of reusable functions:
**sample.sah**
```js
_include("library.sah");
login("test", "secret");
addBooks(2, 1, 1);
verifyTotal(1150);
_click(_button("Logout"));
```
**library.sah**
```js
function login($username, $password){
_setValue(_textbox("user"), $username);
_setValue(_password("password"), $password);
_click(_submit("Login"));
}
function addBooks($numJava, $numRuby, $numPython){
_setValue(_textbox("q"), $numJava);
_setValue(_textbox("q[1]"), $numRuby);
_setValue(_textbox("q[2]"), $numPython);
_click(_button("Add"));
}
function verifyTotal($total){
_assertEqual($total, _textbox("total").value);
}
```
## How Sahi Script Runs
Sahi parses each script and automatically adds reporting, waiting, language translation and error recovery. The result is fully valid JavaScript, which runs in a Rhino JavaScript engine inside Sahi's proxy, in its Java Virtual Machine (JVM). Only the statements that act on the browser are sent to the browser. Everything else runs in Rhino.
So Sahi Script can [call Java code](https://resources.sahipro.com/docs/sahi-script/calling-java/) directly: any Java code on Sahi's classpath. Rhino passes variables between Java and JavaScript automatically.
## See Also
- [Function Reference](https://resources.sahipro.com/docs/sahi-script/functions/)
- [Sahi Scripting Basics](https://resources.sahipro.com/docs/sahi-script/sahi-scripting-basics/)
---
# Download Center
Download the installers for Sahi Pro, Sahi Pro Runner and the Engines, for the latest release and earlier versions.
Each installer needs a product license or a trial license. To start a free trial, [get started here](https://sahipro.com/get-started/).
## Latest Release