#Index
Namespaces
- Sahi-API
- TestCase
- TestCase.addImagePaths(imagePaths)
- TestCase.endOfStep(stepName, optWarningTime, optCriticalTime, optForward)
- TestCase.handleException(e)
- TestCase.saveResult(optForward)
- TestCase.getID()
- TestCase.getLastURL()
- TestCase.getTestCaseFolderPath()
- TestCase.getTestSuiteFolderPath()
- TestCase.throwException(message, screenshot)
- Application
- Environment
- Environment.setSimilarity(similarity)
- Environment.resetSimilarity()
- Environment.getRegionFromFocusedWindow()
- Environment.takeScreenshot(filename)
- Environment.takeScreenshotWithTimestamp(filenamePostfix, optFolderPath, optFormat)
- Environment.sleep(seconds)
- Environment.sleepMs(milliseconds)
- Environment.getClipboard()
- Environment.setClipboard(text)
- Environment.pasteClipboard()
- Environment.copyIntoClipboard()
- Environment.cleanClipboard()
- Environment.paste(text)
- Environment.pasteMasked(text)
- Environment.pasteAndDecrypt(text)
- Environment.type(text, optModifiers)
- Environment.typeMasked(text, optModifiers)
- Environment.typeAndDecrypt(text, optModifiers)
- Environment.decryptSecret(secret)
- Environment.keyDown(keys)
- Environment.keyUp(keys)
- Environment.write(text)
- Environment.mouseWheelDown(steps)
- Environment.mouseWheelUp(steps)
- Environment.isWindows()
- Environment.isLinux()
- Environment.getOsIdentifier()
- Environment.runCommand(command, optThrowException)
- Environment.getEnv(key)
- Environment.getProperty(key)
- Key
- Logger
- MouseButton
- Region
- Region.find(imageName)
- Region.findRegion()
- Region.exists(imageName, optWaitSeconds)
- Region.click()
- Region.doubleClick()
- Region.rightClick()
- Region.mouseMove()
- Region.mouseDown(mouseButton)
- Region.mouseUp(mouseButton)
- Region.dragAndDropTo(targetRegion)
- Region.waitForImage(imageName, seconds)
- Region.paste(text)
- Region.pasteMasked(text)
- Region.pasteAndDecrypt(text)
- Region.type(text, optModifiers)
- Region.typeMasked(text, optModifiers)
- Region.typeAndDecrypt(text, optModifiers)
- Region.keyDown(keys)
- Region.keyUp(keys)
- Region.write(text)
- Region.deleteChars(amountOfChars)
- Region.mouseWheelDown(steps)
- Region.mouseWheelUp(steps)
- Region.move(offsetX, offsetY)
- Region.grow(range)
- Region.grow(width, height)
- Region.above(range)
- Region.below(range)
- Region.left(range)
- Region.right(range)
- Region.setH(height)
- Region.getH()
- Region.setW(width)
- Region.getW()
- Region.setX(x)
- Region.getX()
- Region.setY(y)
- Region.getY()
- Region.highlight(seconds)
- Region.takeScreenshot(filename)
- Region.takeScreenshotWithTimestamp(filenamePostfix, optFolderPath, optFormat)
- Region.sleep(seconds)
- Region.sleepMs(milliseconds)
- Region.extractText()
- RegionRectangle
#Sahi-API All Sahi-API functions are natively usable in Sakuli. For a complete documentation, see Sahi-API.
Members
#TestCase TestCase - initializes the Sakuli object and sets the warning and critical time for this test case.
Params
- optCaseId
String
- optional ID to set the testcase ID to some specifc value. Default is the folder name. - optWarningTime
number
- threshold in seconds. If the threshold is not set or is set to 0, the execution time will never exceed, so the state will be always OK! - optCriticalTime
number
- threshold in seconds. If the threshold is not set or is set to 0, the execution time will never exceed, so the state will be always OK! - optImagePathArray
Array.<String>
- (optional) Path or Array of Paths to the folder containing the image patterns for these test cases.
Returns: - an initialized Sakuli object.
Example
//new syntex since v1.2.0
var testCase = new TestCase(["own-case-id", 20, 30, "path-to/image-folder-name"]);
//old syntax < v1.2.0
var testCase = new TestCase(20, 30, ["path-to/image-folder-name"]);
Members
- TestCase
- TestCase.addImagePaths(imagePaths)
- TestCase.endOfStep(stepName, optWarningTime, optCriticalTime, optForward)
- TestCase.handleException(e)
- TestCase.saveResult(optForward)
- TestCase.getID()
- TestCase.getLastURL()
- TestCase.getTestCaseFolderPath()
- TestCase.getTestSuiteFolderPath()
- TestCase.throwException(message, screenshot)
##TestCase.addImagePaths(imagePaths) Adds the additional paths to the current image library of the TestCase. If a relative path is assigned, the current testcase folder will be used as current directory.
Params
- imagePaths
string
- one or more path strings
##TestCase.endOfStep(stepName, optWarningTime, optCriticalTime, optForward)
A step allows to sub-divide a case to measure logical units, such as "login", "load report" etc. in its
particular runtime. When a case starts, Sakuli starts a "step" timer. It gets read out, stored with the
step name, and the timer will set to 0
each time endOfStep() is called.
If the step runtime exceeds the step warning resp. critical threshold (second resp. third parameter, both of them are optional), the step is saved with state "WARNING" resp. "CRITICAL".
Params
- stepName
String
- optWarningTime
number
- (optional) threshold in seconds, default = 0. If the threshold is set to 0, the execution time will never exceed, so the state will be always OK! - optCriticalTime
number
- (optional) threshold in seconds, default = 0. If the threshold is set to 0, the execution time will never exceed, so the state will be always OK! - optForward
boolean
- (optional) indicate whether the result of the test step shall be immediately processed by the enabled forwarders. This means before the test suite has been executed to the end. If not specified in another way, this option is disabled! Default:false
##TestCase.handleException(e) Handles any Exception or Error. The handleException function calls the Java backend and stores the Exception for further processing.
Use it at the end of a catch-block.
Params
- e
Error
- any Exception or Error
Example
try {
... do something
} catch (e) {
sakuli.handleException(e);
}
##TestCase.saveResult(optForward) Saves the results of the current test case for further processing.
Should be called in finally-block of the test case:
Params
- optForward
boolean
- indicate whether the result of the test case shall be immediately processed by the enabled forwarders. This means before the test suite has been executed to the end. If not specified in another way, this option is disabled! Default:false
Example
try {
... do something
} catch (e) {
sakuli.handleException(e);
} finally {
sakuli.saveResult();
}
##TestCase.getID() Returns the current id of this test case.
Returns: String
- id
##TestCase.getLastURL()
Updates and returns the URL of the last visited URL
Returns: String
- last visited URL
##TestCase.getTestCaseFolderPath()
Returns: String
- the folder path of the current testcase.
##TestCase.getTestSuiteFolderPath()
Returns: String
- the folder path of the current testcase.
##TestCase.throwException(message, screenshot)
Creates a new test case based exception with an optional screenshot at the calling time.
Will be called from sakuli.js or in side of 'org.sakuli.javaDSL.AbstractSakuliTest'.
Params
- message
String
- error message - screenshot
Boolean
- enable / disable screenshot functionality
#Application Application Class - Represents an application.
Params
- applicationNameOrPath
String
- Path to the application file. Example:C:\Windows\system32\notepad.exe
- optResumeOnException
Boolean
- Determines whether to ignore exceptions from this class. If this parameter is undefined, it will be false.
Returns: Application - an initialized object.
Example
//windows
var editor = new Application("notepad.exe");
//linux
var editor = new Application("gedit");
Members
##Application.open() Opens the created application. For application with a long load time you may need to change the default sleep time with setSleepTime(...).
Returns: - this Application object.
##Application.focus()
Focuses the current application, if the application is in the background.
Returns: - this Application object.
##Application.focusWindow(windowNumber)
Focuses a specific window of the application.
Params
- windowNumber
number
- identifies the window
Returns: - this Application object.
##Application.close(optSilent)
Closes the already existing application.
Params
- optSilent
boolean
- (optional) if true, no exception will be thrown on errors and stop the test execution.
Returns: - this Application object.
##Application.kill(optSilent)
Kill the already existing application hardly.
Params
- optSilent
boolean
- (optional) if true, no exception will be thrown on errors.
Returns: - this Application object.
##Application.setSleepTime(seconds)
Sets the sleep time in seconds of the application actions to handle with long loading times.
The default sleep time is set to 1 seconds.
Params
- seconds
number
- sleep time in seconds
Returns: - this Application object.
##Application.getRegion()
Creates and returns a Region object from the application.
Returns: - a Region object.
##Application.getRegionForWindow(windowNumber)
Creates and returns a Region object from a specific window of the application.
Params
- windowNumber
number
- identifies the window
Returns: - a Region object.
##Application.getName()
Returns: - the name of the current application.
#Environment
Environment - Represents the environment of the current test host.
Params
- optResumeOnException
Boolean
- (optional) if this parameter is undefined, it will be false.
Members
- Environment
- Environment.setSimilarity(similarity)
- Environment.resetSimilarity()
- Environment.getRegionFromFocusedWindow()
- Environment.takeScreenshot(filename)
- Environment.takeScreenshotWithTimestamp(filenamePostfix, optFolderPath, optFormat)
- Environment.sleep(seconds)
- Environment.sleepMs(milliseconds)
- Environment.getClipboard()
- Environment.setClipboard(text)
- Environment.pasteClipboard()
- Environment.copyIntoClipboard()
- Environment.cleanClipboard()
- Environment.paste(text)
- Environment.pasteMasked(text)
- Environment.pasteAndDecrypt(text)
- Environment.type(text, optModifiers)
- Environment.typeMasked(text, optModifiers)
- Environment.typeAndDecrypt(text, optModifiers)
- Environment.decryptSecret(secret)
- Environment.keyDown(keys)
- Environment.keyUp(keys)
- Environment.write(text)
- Environment.mouseWheelDown(steps)
- Environment.mouseWheelUp(steps)
- Environment.isWindows()
- Environment.isLinux()
- Environment.getOsIdentifier()
- Environment.runCommand(command, optThrowException)
- Environment.getEnv(key)
- Environment.getProperty(key)
##Environment.setSimilarity(similarity) Set a new default similarity for the screen capturing methods.
Params
- similarity
number
- value between 0 and 1, default = 0.8
Returns: - this Environment or NULL on errors.
##Environment.resetSimilarity()
Resets the current similarity of the screen capturing methods to the original default value of 0.8.
Returns: - this Environment or NULL on errors.
##Environment.getRegionFromFocusedWindow()
Get a Region object from the current focused window
Returns: - a Region object from the current focused window
or NULL on errors.
##Environment.takeScreenshot(filename)
Takes a screenshot of the current screen and saves it to the assigned path. If there ist just a file name, the
screenshot will be saved in your current testcase folder.
Supported formats: jpg
and png
Params
- filename
String
-pathname/filename.format
or justfilename.format
for exampletest.png
.
Returns: Path
- to the created screenshot OR null on errors
Example
environment.takeScreenshot("test.png");
##Environment.takeScreenshotWithTimestamp(filenamePostfix, optFolderPath, optFormat) Takes a screenshot of the current screen and add the current timestamp in the file name like e.g.:
Params
- filenamePostfix
String
- postfix for the final filename Default: screenshot - optFolderPath
String
- optional FolderPath, where to save the screenshot. If null or empty: testcase folder will be used - optFormat
string
- optional format, for the screenshot (currently supported: jpg and png) If null or empty use propertysakuli.screenshot.format
Returns: Path
- to the created screenshot OR null on errors
Example
env.takeScreenshotWithTimestamp("my-screenshot");
saved under: mytestsuite/testcase1/2017_08_03_14_06_13_255_my_screenshot.png
##Environment.sleep(seconds) Blocks the current testcase execution for x seconds
Params
- seconds
number
- to sleep
Returns: - this Environment or NULL on errors.
##Environment.sleepMs(milliseconds)
Blocks the current testcase execution for x milliseconds
Params
- milliseconds
number
- to sleep
Returns: - this Environment or NULL on errors.
##Environment.getClipboard()
Returns: - the current content of the clipboard as String or NULL on errors
##Environment.setClipboard(text)
sets the String parameter to the system clipboard
Params
- text
String
- text as string
Returns: - this Environment.
##Environment.pasteClipboard()
pastes the current clipboard content into the focused area.
Will do the same as "CTRL + V".
Returns: - this Environment.
##Environment.copyIntoClipboard()
copy the current selected item or text to the clipboard.
Will do the same as "CTRL + C".
Returns: - this Environment.
##Environment.cleanClipboard()
Clean the content of the clipboard.
##Environment.paste(text)
pastes the text at the current position of the focus/carret
using the
clipboard and ctrl/cmd-v (paste keyboard shortcut)
Params
- text
String
- a string, which might contain unicode characters
Returns: - this Environment or NULL on errors.
##Environment.pasteMasked(text)
makes a masked paste(String) without any logging.
Params
- text
String
- a string, which might contain unicode characters
Returns: - this Environment or NULL on errors.
##Environment.pasteAndDecrypt(text)
combines pasteMasked(String) and decryptSecret(String).
Params
- text
String
- encrypted secret
Returns: - this Environment or NULL on errors.
##Environment.type(text, optModifiers)
Enters the given text one character/key after another using keyDown/keyUp.
About the usable Key constants see documentation of Key. The function could also type UTF-8 unicode characters, if the OS supports it. The text is entered at the current position of the focus.
Params
- text
String
- containing characters and/or Key constants - optModifiers
String
- (optional) an String with only Key constants.
Returns: - this Environment or NULL on errors.
##Environment.typeMasked(text, optModifiers)
Enters the given text one character/key after another using keyDown/keyUp.
The entered text will be masked at the logging.
About the usable Key constants see documentation of Key. The function could also type UTF-8 unicode characters, if the OS supports it. The text is entered at the current position of the focus.
Params
- text
String
- containing characters and/or Key constants - optModifiers
String
- (optional) an String with only Key constants.
Returns: - this Environment or NULL on errors.
##Environment.typeAndDecrypt(text, optModifiers)
Decrypt and enters the given text one character/key after another using keyDown/keyUp.
The entered text will be masked at the logging. For the details of the decryption see decryptSecret(String).
About the usable Key constants see documentation of Key. The function could also type UTF-8 unicode characters, if the OS supports it. The text is entered at the current position of the focus.
Params
- text
String
- containing characters and/or Key constants - optModifiers
String
- (optional) an String with only Key constants.
Returns: - this Environment or NULL on errors.
##Environment.decryptSecret(secret)
Decrypt a encrypted secret and returns the value at runtime.
The decryption will only work like described at https://github.com/ConSol/sakuli/blob/master/docs/manual/testdefinition/advanced-topics/sakuli-encryption.adoc .
There will be no logging with the decrypted secret during this step.
To create a encrypted secret see "sakuli-manual.md".
Params
- secret
String
- encrypted secret as String
Returns: - decrypted String
##Environment.keyDown(keys)
Press and hold the given keys including modifier keys
use the key constants defined in class Key,
which only provides a subset of a US-QWERTY PC keyboard layout
might be mixed with simple characters
use + to concatenate Key constants
Params
- keys
String
- valid keys
Returns: - this Environment or NULL on errors.
##Environment.keyUp(keys)
release the given keys (see Environment.keyDown(...)).
Params
- keys
String
- valid keys
Returns: - this Environment or NULL on errors.
##Environment.write(text)
Compact alternative for type() with more options
- special keys and options are coded as #XN. or #X+ or #X-
where X is a refrence for a special key and N is an optional repeat factor
A modifier key as #X. modifies the next following key
the trailing . ends the special key, the + (press and hold) or - (release) does the same,
but signals press-and-hold or release additionally.
except #W / #w all special keys are not case-sensitive
a #wn. inserts a wait of n millisecs or n secs if n less than 60
a #Wn. sets the type delay for the following keys (must be > 60 and denotes millisecs) - otherwise taken as normal wait
Example: wait 2 secs then type CMD/CTRL - N then wait 1 sec then type DOWN 3 times
Windows/Linux: write("#w2.#C.n#W1.#d3.")
Mac: write("#w2.#M.n#W1.#D3.")
for more details about the special key codes and examples consult the sikuliX docs
Params
- text
String
- a coded text interpreted as a series of key actions (press/hold/release)
Returns: - this Environment or NULL on errors.
##Environment.mouseWheelDown(steps)
move the mouse pointer to the given target location and move the
wheel the given steps down.
Params
- steps
number
- the number of steps
##Environment.mouseWheelUp(steps) move the mouse pointer to the given target location and move the wheel the given steps up.
Params
- steps
number
- the number of steps
##Environment.isWindows()
Returns: boolean
- true, if the OS is any instance of an Windows based OS
##Environment.isLinux()
Returns: boolean
- true, if the OS is any instance of an Linux based OS
##Environment.getOsIdentifier()
Returns: string
- identifier of the current OS
##Environment.runCommand(command, optThrowException)
Runs the assigned command on the host and returns the result. Attention: this is OS depended feature! So be
aware which os you are running, maybe us to check Environment#isLinux()
or Environment#isWindows()
.
Params
- command
string
- OS depended command asString
- optThrowException
boolean
- defines if an exception should be thrown, if the exit code != 0
Returns: - the result as CommandLineResult
object, you can use the methods result.getOutput()
and result.getExitCode()
Example
var app;
if(environmen.runCommand('uname --machine') == 'x86_64'){
//open app from other path
app = new Application('/lib64/appname');
} else {
app = new Application('/lib/appname');
}
##Environment.getEnv(key) Reads out the environment variable with the assigned key
Params
- key
string
- of environment variable
Returns: string
- value or null
##Environment.getProperty(key)
Reads out the property value with the assigned key
Params
- key
string
- of property
Returns: string
- value or null
#Key
All non-character keys are represented by Key constants which can be used in type functions.
The following Key values are available:
SPACE
, ENTER
, BACKSPACE
, TAB
, ESC
, UP
, RIGHT
, DOWN
, LEFT
, PAGE_UP
, PAGE_DOWN
, DELETE
, END
,
HOME
, INSERT
, F1
, F2
, F3
, F4
, F5
, F6
, F7
, F8
, F9
, F10
, F11
, F12
, F13
, F14
, F15
,
SHIFT
, CTRL
, ALT
, ALTGR
, META
, CMD
, WIN
, PRINTSCREEN
, SCROLL_LOCK
, PAUSE
, CAPS_LOCK
, NUM0
,
NUM1
, NUM2
, NUM3
, NUM4
, NUM5
, NUM6
, NUM7
, NUM8
, NUM9
, SEPARATOR
, NUM_LOCK
, ADD
, MINUS
,
MULTIPLY
, DIVIDE
, DECIMAL
, CONTEXT
Example
Press F1
:
env.type(Key.F1);
Close a window by typing the shortcut ALT + F4
// the second parameter is the held (="modifier") key
env.type(Key.F4, Key.ALT);
Open the file manager on Windows with shortcut WIN + e
:
env.type("e", Key.META)
Do something application specific with shortcut CTRL + ALT + b
(CTRL + ALT = ALTGR):
env.type("b", Key.ALTGR)
Closing an window over typing the short cut ALT + F4
:
env.type(Key.F4, Key.ALT);
Using Key.ALTGR
on Unix:
TIP: To enable the key command ALTGR
on unix systems please bind it to CTRL + ALT
. For more information
see stackexchange.com - how-to-bind-altgr-to-ctrl-alt.
Members
#Logger Logger - Logging functions to do 'debug, 'info', 'warning' and 'error' log entries.
Members
##Logger.logError(message) make a error-log over Java backend into the log file. This won't stop the execution of the test case.
Params
- message
String
- as a String
##Logger.logWarning(message) make a debug-log over Java backend into the log file.
Params
- message
String
- as a String
##Logger.logInfo(message) make a info-log over Java backend into the log file.
Params
- message
String
- as a String
##Logger.logDebug(message) make a debug-log over Java backend into the log file.
Params
- message
String
- as a String
#MouseButton MouseButton - representing the possible mouse action button.
The following MouseButton values are possible:
LEFT
, RIGHT
, MIDDLE
Example
Press and release the right mouse button for 3 seconds on a specified region:
var region = new Region().find("your-pattern.png");
region.mouseDown(MouseButton.RIGHT).sleep(3).mouseUp(MouseButton.RIGHT);
Members
#Region Region - Represents a region as a part of or the hole screen.
Params
- optResumeOnException
Boolean
- if true, the test execution won't stop on an occurring error. Default: false.
Example
var screen = new Region(); //represents the hole screen
Members
- Region
- Region.find(imageName)
- Region.findRegion()
- Region.exists(imageName, optWaitSeconds)
- Region.click()
- Region.doubleClick()
- Region.rightClick()
- Region.mouseMove()
- Region.mouseDown(mouseButton)
- Region.mouseUp(mouseButton)
- Region.dragAndDropTo(targetRegion)
- Region.waitForImage(imageName, seconds)
- Region.paste(text)
- Region.pasteMasked(text)
- Region.pasteAndDecrypt(text)
- Region.type(text, optModifiers)
- Region.typeMasked(text, optModifiers)
- Region.typeAndDecrypt(text, optModifiers)
- Region.keyDown(keys)
- Region.keyUp(keys)
- Region.write(text)
- Region.deleteChars(amountOfChars)
- Region.mouseWheelDown(steps)
- Region.mouseWheelUp(steps)
- Region.move(offsetX, offsetY)
- Region.grow(range)
- Region.grow(width, height)
- Region.above(range)
- Region.below(range)
- Region.left(range)
- Region.right(range)
- Region.setH(height)
- Region.getH()
- Region.setW(width)
- Region.getW()
- Region.setX(x)
- Region.getX()
- Region.setY(y)
- Region.getY()
- Region.highlight(seconds)
- Region.takeScreenshot(filename)
- Region.takeScreenshotWithTimestamp(filenamePostfix, optFolderPath, optFormat)
- Region.sleep(seconds)
- Region.sleepMs(milliseconds)
- Region.extractText()
##Region.find(imageName) Finds an image inside this region immediately.
Params
- imageName
String
- name of the preloaded picture (if not set, the find operation will take place on the predefined region object.)
Returns: - the found Region or if the target can't be found null.
##Region.findRegion()
Finds a target in this Region immediately;
Returns: - the found Region or if the target can't be found null.
##Region.exists(imageName, optWaitSeconds)
Check whether the give pattern is visible on the screen.
Params
- imageName
String
- if set, the function search inside the given region for the image - optWaitSeconds
number
- if set, the function search for x seconds for the pattern.
Returns: - this Region or null
##Region.click()
makes a mouse click on the center of the Region.
Returns: - the Region or NULL on errors.
##Region.doubleClick()
makes a double click on the center of the Region.
Returns: - the Region or NULL on errors.
##Region.rightClick()
makes a right click on the center of the Region.
Returns: - the Region or NULL on errors.
##Region.mouseMove()
Move the mouse pointer to the center of the Region and "hovers" it.
Returns: - the Region or NULL on errors.
##Region.mouseDown(mouseButton)
Low-level mouse action to press the assigned MouseButton on the current position.
Params
- mouseButton - on of MouseButton values
Returns: - the Region or NULL on errors.
Example
Press and release the right mouse button for 3 seconds on a specified region:
var region = new Region().find("your-pattern.png");
region.mouseDown(MouseButton.RIGHT).sleep(3).mouseUp(MouseButton.RIGHT);
##Region.mouseUp(mouseButton) Low-level mouse action to release the assigned MouseButton.
Params
- mouseButton - on of MouseButton values
Returns: - the Region or NULL on errors.
Example
Press and release the right mouse button for 3 seconds on a specified region:
var region = new Region().find("your-pattern.png");
region.mouseDown(MouseButton.RIGHT).sleep(3).mouseUp(MouseButton.RIGHT);
##Region.dragAndDropTo(targetRegion) Drag from region's current position and drop at given targetRegion and using the left mouse.
Params
- targetRegion
Region
- target where to drop
Returns: - the Region or NULL on failure
Example
move the bubble button 20px to the right:
var bubble = screen.find("bubble.png");
bubble.dragAndDropTo(bubble.right(20));
##Region.waitForImage(imageName, seconds) Blocks and waits until a target which is specified by the optImageName is found in the hole Screen within a given time period in seconds.
Params
- imageName
String
- name of the image pattern - seconds
number
- the maximum time to waitFor in seconds
Returns: - a Region object representing the region occupied by the found target,
or null if the target can not be found within the given time.
##Region.paste(text)
pastes the text at the current position of the focus/carret
using the
clipboard and ctrl/cmd-v (paste keyboard shortcut)
Params
- text
String
- as a string, which might contain unicode characters
Returns: - this Region or NULL on errors.
##Region.pasteMasked(text)
makes a masked paste(String) without any logging.
Params
- text
String
- a string, which might contain unicode characters
Returns: - this Region or NULL on errors.
##Region.pasteAndDecrypt(text)
combines pasteMasked(String) and decryptSecret(String).
Params
- text
String
- encrypted secret
Returns: - this Region or NULL on errors.
##Region.type(text, optModifiers)
Enters the given text one character/key after another using keyDown/keyUp.
About the usable Key constants see documentation of Key. The function could also type UTF-8 unicode characters, if the OS supports it. The text is entered at the current position of the focus.
Params
- text
String
- containing characters and/or Key constants - optModifiers
String
- (optional) an String with only Key constants.
Returns: - this Region or NULL on errors.
##Region.typeMasked(text, optModifiers)
Enters the given text one character/key after another using keyDown/keyUp.
The entered text will be masked at the logging.
About the usable Key constants see documentation of Key. The function could also type UTF-8 unicode characters, if the OS supports it. The text is entered at the current position of the focus.
Params
- text
String
- containing characters and/or Key constants - optModifiers
String
- (optional) an String with only Key constants.
Returns: - this Region or NULL on errors.
##Region.typeAndDecrypt(text, optModifiers)
Decrypt and enters the given text one character/key after another using keyDown/keyUp.
The entered text will be masked at the logging. For the details of the decryption see decryptSecret(String).
About the usable Key constants see documentation of Key. The function could also type UTF-8 unicode characters, if the OS supports it. The text is entered at the current position of the focus.
Params
- text
String
- containing characters and/or Key constants - optModifiers
String
- (optional) an String with only Key constants.
Returns: - this Region or NULL on errors.
##Region.keyDown(keys)
Press and hold the given keys including modifier keys
use the key constants defined in class Key,
which only provides a subset of a US-QWERTY PC keyboard layout
might be mixed with simple characters
use + to concatenate Key constants
Params
- keys
String
- valid keys
Returns: - this Region or NULL on errors.
##Region.keyUp(keys)
release the given keys (see Region.keyDown(...)).
Params
- keys
String
- valid keys
Returns: - this Region or NULL on errors.
##Region.write(text)
Compact alternative for type() with more options
- special keys and options are coded as #XN. or #X+ or #X-
where X is a refrence for a special key and N is an optional repeat factor
A modifier key as #X. modifies the next following key
the trailing . ends the special key, the + (press and hold) or - (release) does the same,
but signals press-and-hold or release additionally.
except #W / #w all special keys are not case-sensitive
a #wn. inserts a wait of n millisecs or n secs if n less than 60
a #Wn. sets the type delay for the following keys (must be > 60 and denotes millisecs) - otherwise taken as normal wait
Example: wait 2 secs then type CMD/CTRL - N then wait 1 sec then type DOWN 3 times
Windows/Linux: write("#w2.#C.n#W1.#d3.")
Mac: write("#w2.#M.n#W1.#D3.")
for more details about the special key codes and examples consult the sikuliX docs
Params
- text
String
- a coded text interpreted as a series of key actions (press/hold/release)
Returns: - this Region or NULL on errors.
##Region.deleteChars(amountOfChars)
delete a amount of chars in a field
Params
- amountOfChars
number
- number of chars to delete
Returns: - this Region or null on errors
##Region.mouseWheelDown(steps)
move the mouse pointer to the given target location and move the
wheel the given steps down.
Params
- steps
number
- the number of steps
##Region.mouseWheelUp(steps) move the mouse pointer to the given target location and move the wheel the given steps up.
Params
- steps
number
- the number of steps
##Region.move(offsetX, offsetY) Set a offset to a specific Region and returns the new Region object. The offset function will move the Region's rectangle x pixels to the right and y pixels down. The size of the rectangle will be the same.
Params
- offsetX
number
- x-value for the offset action - offsetY
number
- y-value for the offset action
Returns: - a Region with the new coordinates
##Region.grow(range)
create a region enlarged range pixels on each side
Params
- range
number
- of pixels
Returns: - a new Region
##Region.grow(width, height)
create a region with enlarged range pixels
Params
- width
number
- in pixels to grow in both directions - height
number
- in pixels to grow in both directions
Returns: - a new Region
##Region.above(range)
Params
- range
number
- of pixels
Returns: - a new Region that is defined above the current region’s top border
with a height of range number of pixels.
##Region.below(range)
Params
- range
number
- of pixels
Returns: - a new Region that is defined below the current region’s bottom border
with a height of range number of pixels.
##Region.left(range)
Params
- range
number
- of pixels
Returns: - a new Region that is defined on the left the current region’s left border
with a width of range number of pixels.
##Region.right(range)
Params
- range
number
- of pixels
Returns: - a new Region that is defined on the right the current region’s right border
with a width of range number of pixels.
##Region.setH(height)
set the height, based form the upper left corner downsides
Params
- height
number
- in pixels
##Region.getH()
Returns: - height as int value
##Region.setW(width)
set the width, based form the upper left corner to the right
Params
- width
number
##Region.getW()
Returns: - width as int value
##Region.setX(x)
set the X coordinate of the upper left corner.
Params
- x
number
##Region.getX()
Returns: - width as int value
##Region.setY(y)
set the Y coordinate of the upper left corner.
Params
- y
number
##Region.getY()
Returns: - Y coordinate of the upper left corner
##Region.highlight(seconds)
Params
- seconds
number
- highlights this Region for x seconds or the default time
##Region.takeScreenshot(filename)
Takes a screenshot of this Region and saves it to the assigned path. If there ist just a file name, the
screenshot will be saved in your current testcase folder.
Supported formats: jpg
and png
Params
- filename
String
-pathname/filename.format
or justfilename.format
for exampletest.png
.
Returns: Path
- to the created screenshot OR null on errors
Example
region.takeScreenshot("test.png");
##Region.takeScreenshotWithTimestamp(filenamePostfix, optFolderPath, optFormat) Takes a screenshot of this Region and add the current timestamp in the file name like e.g.:
Params
- filenamePostfix
String
- postfix for the final filename Default: screenshot - optFolderPath
String
- optional FolderPath, where to save the screenshot. If null or empty: testcase folder will be used - optFormat
string
- optional format, for the screenshot (currently supported: jpg and png) If null or empty use propertysakuli.screenshot.format
Returns: Path
- to the created screenshot OR null on errors
Example
region.takeScreenshotWithTimestamp("my-screenshot");
saved under: mytestsuite/testcase1/2017_08_03_14_06_13_255_my_screenshot.png
##Region.sleep(seconds) Blocks the current testcase execution for x seconds
Params
- seconds
number
- to sleep
Returns: - this Region or NULL on errors.
##Region.sleepMs(milliseconds)
Blocks the current testcase execution for x milliseconds
Params
- milliseconds
number
- to sleep
Returns: - this Region or NULL on errors.
##Region.extractText()
Returns: - from this region a extracted Text as String
#RegionRectangle
RegionRectangle (extends Region) - Represents a region specified by the x and y coordinates, width and
height as a part of the screen.
Params
- x
number
- – x position of a rectangle on the screen. - y
number
- – y position of a rectangle on the screen. - w
number
- – width of a rectangle in pixel. - h
number
- – height of a rectangle in pixel. - optResumeOnException
Boolean
- (optional) if true, the test execution won't stop on an occurring error. Default: false.
Example
var notepadRegion = new RegionRectangle(0,0,100,100);
//represents a region which start at x=0, y=o (left upper corner) and have a size of 100px * 100px.
Members