Command Summary

T-Plan Robot contains a number commands spanning a variety of purposes. Below we provide a brief summary of each command, in alphabetical order, with a link through to more information.

Some of the most popular or commonly used commands are:

Report - ensures that each execution generates and output report.
Click image/ocr/object - visually search for an item on the screen and click on it if found.
Browser open/find - object recognition for web automation.
Mobile find - object recognition for mobile device automation.
Screenshot - capture a live screenshot
Type or Paste - pass a text string to be typed into the target system.
If/else - dynamically branch behaviour based on any given criteria.
For - loop any number of times/values or until a condition has been met.
Var/Varg - define custom variables for use across your script executions
Procedure - create reusable pieces of code to help streamline your scripts.

T-Plan Robot Command Summary
	Category	Command		Description
A	Administrative and Execution Control Commands	Alert		An alert window pops up on your local machine. The window can be customized to include custom buttons and editable fields. It can also be automatically discarded after a specified timeout.
B	Administrative and Execution Control Commands	Break		Immediately exit the innermost 'for' loop and proceed to the first command after the right curly curly brace '}' surrounding the loop. If the command is used outside of the for loop, a syntax error is reported. To skip the current loop without interrupting the 'for' command, use the continue command.
	Desktop Commands	Browser		Automate web browsers, via Selenium drivers, using web element object identification. (not image based).
			Browser open	Open the web browser of your choice and load the specified web page. The browser can be either a local browser or a remote browser (supported by Selenium Grid, 6.3 or later). In version 8 and later, you can also open a new tab or window with this command.
			Browser find	Search for elements on the web page according to the specified object criteria and apply optional actions (click, type, submit, clear). If the command does not specify an action and the element is not found, the script continues. The search results (found/missing) are indicated in the script by the command's exit code and the presence of _WEB variables containing element attributes. If the command specifies an action and the element is not found, the script is terminated. This behaviour is consistent with 'click' and 'drag' commands.



			Browser switch	Switch between browser tabs and windows. Supported in v8 and later.
			Browser close	Close the tab, window, or entire browser and finally end the Selenium session.
C	Administrative and Execution Control Commands	Compareto		Immediately perform a single search of the connected SUT using any of the available search methods (image, text, object, AI, etc)
	Desktop Commands	Connect		Connect to your target SUA (system under automation). Many features rely on a live connection, including: desktop execution, record & playback, search debugging, etc.
	Administrative and Execution Control Commands	Continue		Skip iterations of the current innermost for loop. If the command is used outside of the 'for' loop, a syntax error is reported. To interrupt (terminate) the entire 'for' loop, use the break command.
	Administrative and Execution Control Commands	Click		Wait for an item to appear before then clicking it. Utilize any of the search methods (image, text, object, AI) and if the object is not found within the given timeout (default 30s), exit the script.
D	Administrative and Execution Control Commands	Date		It reads, writes, and calculates dates. This command allows you to retrieve the current date, parse the entered date, optionally perform a time increase or decrease operation, and save the results in a _DATE variable in the specified format or in a specified custom variable.
	Desktop Commands	Disconnect		Disconnect from the SUA. When the connection is closed, the predefined variables _MACHINE and _DISPLAY are cleared.
	Administrative and Execution Control Commands	Drag		Locate the start and end points of a mouse drag action through any of the available search methods, or via a relative distance. If either of the searches fail, exit the script.
	Administrative and Execution Control Commands	Drag
E	Administrative and Execution Control Commands	Eval		Define script variables whose values are evaluated as numeric expressions. For more information, see the chapter on numerical formulas. Other behaviour is exactly the same as the var command.
		Exec		Run OS commands on your local system (the machine running T-Plan Robot). The argument must be a single command (e.g., 'ls -l' on Unix/Linux). Due to the limitations of the interface between Java and the underlying OS, commands do not allow pipes and redirects of output. If you need to save the output to a file, use the outfile parameter. If you need to use a pipe or redirect, place the command in a shell script or batch file and call it with an Exec command instead.
		Exit		Terminate a script, procedure, or structured block of code and return an exit code.
	I/O Commands	Excel		Read, write and search Microsoft Excel files (.xls, .xlsx, xlsm). This command allows you to programmatically (not via any UI) navigate through spreadsheets available to your local system. This command is not reliant on a live SUA connection.
		Excel
			Open	Opens an existing Excel document in read/write mode.
			Create	Create a new Excel document and/or create a sheet.
			Select	Select a sheet and/or select a cell and retrieve its value and format.
			Find	Search the selected sheet for a cell by its value or a regular expression.
			Set	Set sheet name or cell value (format).
			Copy	Mark cells for copying.
			Paste	Paste cells marked with Copy into an Excel document.
			Close	Close and save the Excel document.
F	I/O Commands	File		Reading from and/or writing to text files. You can use this command to open or create plain text files, read/write text, search for strings/regular expressions, and parse values from individual text lines using comma-separated values (CSV) format or regular expressions.
F	Language Structure	For		Design a loop to iterate over a range of values or based on a specified condition.
G	Desktop Commands	Gesture		Design and execute touch screen gestures. It is only supported on mobile device connections such as: Android via ADB, iOS via Xcode
			Gesture press	Record finger presses at the specified location in the gesture buffer.
			Gesture move	Records the movement (drag) of the specified finger to a new location.
			Gesture release	Record the release of the specified finger.
			Gesture save	Save the gesture with the given name and clear the gesture buffer.
			Gesture execute	Perform gestures on connected devices to clear gesture buffers.
			Gesture clear	Clear the gesture buffer and get ready to design new gestures
I	Language Structure	If/else		Use the if/else commands to dynamically branch execution flows based on given values.
	Administrative and Execution Control Commands	Image doctor		The Image Doctor wizard can help you identify and resolve image comparison failures in executed scripts. This is especially useful if your application or System Under Automation (SUA) changes and you need to update your image comparison code or template images. The wizard consists of three elements: Image Doctor's warning pop-up window allows you to interactively resolve image comparisons. The Image Doctor Records feature records failed image comparisons in automated (unattended) mode for later resolution. The ImageDoctor command controls the behaviour of the feature directly from the script.



		Include		Include another script or compiled Java code. If the argument is a TPR script in the language described in this document, the command will load only the procedures and variables from the script into the execution context and make them available in the calling script. This principle allows you to build a library with globally used variables and procedures and link them to your script.
		Include
J	Language Structure	Java		Create a native Java code block directly within your TPR script to leverage the full power of Java capabilities.
L	Reporting Commands	Log		Log the message in the script execution log file.
M	Administrative and Execution Control Commands	Moveto		It is a combination of the Waitfor match and Mouse move commands. Search for component images, solid colour objects, or text on your desktop, and hover your mouse pointer there. If the object is not found, exit the script.
	I/O Commands	Mail		Get incoming mail from an IMAP or POP3 server. To send an email through an SMTP server, use the Sendmail command.
			Mail get	Download the email from the server. Messages can optionally be filtered by attributes.
			Mail set	Set the SEEN flag for the message.
			Mail delete	Delete one or more messages on the server.
	Desktop Commands	Mouse		Run a mouse event. This command can automate various mouse actions, such as moving the mouse pointer, clicking, pressing, releasing it, dragging, and mouse wheel events. This command also supports custom dragging, which consists of a sequence of mouse press, mouse movement, and mouse release events (starting in 2.0.2). If the configured events (click, drag) fail, check the adjustment parameters in the mouse command settings. The coordinates of the current mouse pointer are available in the script through _MOUSE_X and _MOUSE_Y dynamic variables (version 2.1 and later).
		Mouse
			Mouse click	Perform one or more clicks at the target point using the specified mouse button
			Mouse drag	Use the designated mouse button to drag the mouse from any destination to the target point.
			Mouse move	Move the mouse pointer from any destination to the target point.
			Mouse pinch	It is one or more pinch events that move two fingers toward a common center point on the touch screen (also known as a "pinch close"). This event is only supported in certain environments, such as Apple iOS devices running T-Plan Server connected with the iOS mirror connection type.
			Mouse press	Press the mouse button (without releasing it)
			Mouse release	Mouse button release (logically requires a preceding 'press' event)
			Mouse swipe	A mouse drag with adjusted timing for devices with a touch display (such as Android or iOS devices),
			Mouse wheeldown	Rotate the mouse wheel upwards for at least one turn (the wheel rotates away from the user)
			Mouse wheelup	Rotate the mouse wheel downwards at least once (rotate the wheel towards the user)
			Mouse zoom	Zoom in on the screen. If your current connection supports pinch, expand your current application. This command uses a custom center point and start and end distance.
		Mobile		It provides mobile-specific functionality with Android Over ADB and iOS Over Xcode connectivity.
			Mobile alert	Alert processing
			Mobile app	Get your current app ID
			Mobile find	Find and action UI elements through object recognition
			Mobile install	Install apps on your device
			Mobile keyboard	Keyboard Controls
			Mobile kill	Force quit an app on your device
			Mobile orientation	Handling screen orientation
			Mobile pull	Download files from your device
			Mobile push	Upload files to your device
			Mobile shell	Run shell commands against your device
			Mobile start	Launch the app on your device
			Mobile uninstall	Uninstall apps from your device
P	Desktop Commands	Paste		Use the system clipboard to paste (insert) text. Instead of typing text on the keyboard one letter at a time, this command simulates copying the text to the clipboard and pressing Ctrl+V (Command+V on Mac OS X) to trigger the system's paste action. This is much faster than typing text in Type/Typeline.
	Administrative and Execution Control Commands	Pause		Pause the script execution. When the T-Plan Robot is running in GUI mode, the Pause button/menu item is selected and the user can deselect the button or menu item to resume the run. If the script is running in CLI mode, a message is printed to the console and the user can press a key to resume execution.
	Administrative and Execution Control Commands	Pause
	Desktop Commands	Press		Send the key to the desktop. It's the same as pressing a key on a keyboard.
	Language Structure	Procedure		Create reusable pieces of code to streamline your scripts. Procedures can accept numbered variable inputs defined as part of the procedure call.
R	Reporting Commands	Report		Create and launch a reporting provider for the scripts that have been executed. This is an object that creates reports from script execution data, such as results, screenshots, and warnings.
	Administrative and Execution Control Commands	Run		Execute another local TPR script, Java script or Java class. Data and variables and reports generated by executed scripts become available to the calling script also.


S	Reporting Commands	Screenshot		Take a screenshot of your current remote desktop and save it to a file.
		Script		Define the start or end of the script (test case). This command was introduced as part of its integration with T-Plan Professional, but it can be used generally to define scripting structures that are common in the QA industry. Script mappings are recognized by enterprise reporting providers and can be used to map output XML data (or HTML reports) to QA documents (such as test case specifications).
		Sendmail		Send an email. This command acts as an SMTP client and sends emails with attachments through the SMTP server. To receive an email, use the Mail command.
		Step		Define the results of the test step. A step represents a single atomic instruction in a test case (script). The steps must be placed within the script block.
	Administrative and Execution Control Commands	String		Parse or process complex text strings using a one or more String operation. (for basic string validation use a Boolean expression of "contains", "startswith", "endswith" and "matches" within an if/else statement)
			String indexof	Locate the position of the first match to the value supplied in the "string=" parameter.
			String length	Returns the length of the text (number of characters). For example, "String length "Demo" sets the _STRING variable to 4.
			String matches	Matches the text to the java.util.regex.Pattern-compliant regular expression specified in the 'pattern' parameter to produce a Boolean result ('true' or 'false').
			String replace	Returns a new text that replaces all occurrences of the values specified in the 'string' parameter in the text with the string specified by the 'replacement' parameter.
			String split	Split the text into a set of strings that match the specified string ('string' parameter) or java.util.regex.Pattern regular expression ('pattern').
			String substring	Returns a substring of text defined by the entered "start" and/or "end" index number.
			String tostring	Create new text from one or more numeric ASCII or Unicode values separated by semicolons.
			String trim	Remove all leading and trailing spaces (spaces, newline characters, etc.).
T	Reporting Commands	Timer		Manage timer and timer groups. Timers allow you to measure the elapsed time of commands, command blocks, or scripts, typically for performance testing purposes.
T	Desktop Commands	Type/Typeline		Type text on your desktop. The Typeline command is a useful command that simply involves typing text and pressing Enter. This has the same effect as the combination of 'Type <text>' and 'Press Enter'.
V	Administrative and Execution Control Commands	Var		Define standard variables for use throughout your script.
		Varf		Define formatted variables that can contain a Java escape sequence that allows you to insert new lines, tabs, or special Unicode characters into the value.
		Varg		Define ("Varg set") or delete ("Varg delete") global variables with a specified visibility scope, allowing to share data across scripts & workitems.
			Varg set	Varg set name="S" value="Hello" scope="session" - Create or set a session variable called "S"
			Varg delete	Varg delete name="S" scope="session" - Deletes the session variable created in the previous example. Leave all other variables with the same name that exist locally or in the script scope.
W	Administrative and Execution Control Commands	Wait		Wait for the specified time. Use this command to pause the script from running for a specified period of time.
	Reporting Commands	Warning		Insert a warning into the report. Warnings can be associated with specific screenshots through image parameters. Such warnings appear below the image description in the report. If there are no associated images, the alert appears in the report as a single component.
		Waitfor Command		Pause the script execution and wait for the RFB event or the state of the remote desktop image.
			Waitfor bell	Indicates that the server has beeped. This indicates that the application has output a bell character (ASCII 0x07).
			Waitfor clipboard	Wait for the remote server's clipboard content to be delivered, then available through the "_SERVER_CLIPBOARD_CONTENT" variable.
			Waitfor match	The event will cause the command to wait until the selected comparison method produces a positive result (until the desktop matches).
			Waitfor mismatch	Wait until the search can no longer find a match to the item on the screen.
			Waitfor update	Wait for the remote system display to update/change.