Squish API

本节介绍了Squish除了支持的脚本语言的标准功能外还提供的API。Squish API提供了测试工程师测试GUI应用程序所需的设施，提供了从与AUT对象交互、记录测试日志信息，执行验证、控制AUT等功能在内的广泛功能。

Squish API函数

以下是Squish API函数的快速链接（不包括Squish对象或工具包特定的便利函数）

Squish API 函数参数

对于所有接受 objectOrName 参数的 Squish API 函数，它可以是对象的引用或对象名称。

一些 Squish API 函数可以接受一个表示在鼠标点击时按下的特殊键的 modifierState 参数。此外，一些函数接受一个表示哪个鼠标按钮被点击的 mouseButton 参数。

modifierState 可以是 0（Modifier.NoModifier，默认值），或者是以下之一：Modifier.Alt、Modifier.Control、Modifier.Shift。如果使用了多个修改键，它们必须通过 OR 连接。例如，Modifier.Alt|Modifier.Shift。这里所示的形式适用于 Python 和 JavaScript。对于 Perl 和 Ruby，请将点替换为两个冒号：Modifier::Control。对于 Tcl，使用 enum 函数：enum Modifier Control。

mouseButton 可以是以下之一：MouseButton.LeftButton、MouseButton.MiddleButton、MouseButton.RightButton 或 MouseButton.NoButton。

对于 Perl 使用： MouseButton::LeftButton 等。

对于 Ruby 使用： MouseButton::LEFT_BUTTON 等。

对于 Tcl 使用： enum MouseButton LeftButton 等。

确定对象

许多 API 函数适用于特定的对象，因此能够确定感兴趣的对象尤为重要。

Squish提供多种命名方案，但通常使用的是符号名和实际名。符号名在面对自动测试单元（AUT）变化时最为稳健，但实际名有时候使用起来可能会更方便。有关名称的更多信息，请参阅如何识别和访问对象。

对于Qt程序，在代码中对所有感兴趣的Object设置对象名称是识别对象的简单且可靠的方法（使用QObject::setObjectName方法），然后在测试脚本中使用真实的多属性名称指定对象的objectName和其type。例如

textEdit = findObject("{objectName='ConfigEditor' type='QTextEdit'}")

var textEdit = findObject("{objectName='ConfigEditor' type='QTextEdit'}");

my $textEdit = findObject("{objectName='ConfigEditor' type='QTextEdit'}");

textEdit = findObject("{objectName='ConfigEditor' type='QTextEdit'}")

set textEdit [findObject "{objectName='ConfigEditor' type='QTextEdit'}"]

在实践中，给每个单独的widget分配一个唯一对象名称会很繁琐（目前只有Qt支持它），因此这种方法通常在同一个表单中有两个或更多相同的widget时使用。对于那些没有对象名称的工具包，我们可以使用反思方法当有两个或更多相同的widgets时。两种方法的具体示例请参阅如何创建测试脚本和如何测试应用程序 - 专用细节。

最常见的场合是需要识别未命名的对象。这可以通过使用符号名或通过匹配对象的唯一属性值集来完成。必要的信息可以使用Spy工具（如何使用Spy）来获取。此工具可以提供对象的符号名和基于属性（真实）的名称。另一种方法是创建一个空测试，与感兴趣的object交互，然后查看Squish的对象映射以查看Squish使用的名称，并复制所需的任何名称。

以下是一个示例，展示了找到类型为QTextEdit的未命名对象的两种方法。这个对象在QMainWindow中，其标题是“我的应用”。

# symbolic name
textEdit = waitForObject(":MyApp_QTextEdit")
# real (multi-property) name
textEdit = waitForObject("{type='QTextEdit' unnamed='1' " +
        "visible='1' window=':MyApp_MainWindow'}")

// symbolic name
var textEdit = waitForObject(":MyApp_QTextEdit");
// real (multi-property) name
var textEdit = waitForObject("{type='QTextEdit' unnamed='1' " +
        "visible='1' window=':MyApp_MainWindow'}");

# symbolic name
my $textEdit = waitForObject(":MyApp_QTextEdit");
# real (multi-property) name
my $textEdit = waitForObject("{type='QTextEdit' unnamed='1' " .
        "visible='1' window=':MyApp_MainWindow'}");

# symbolic name
textEdit = waitForObject(":MyApp_QTextEdit")
# real (multi-property) name
textEdit = waitForObject("{type='QTextEdit' unnamed='1' " +
        "visible='1' window=':MyApp_MainWindow'}")

# symbolic name
set textEdit [waitForObject ":MyApp_QTextEdit"]
# real (multi-property) name
set textEdit [waitForObject "{type='QTextEdit' unnamed='1' \
        visible='1' window=':MyApp_MainWindow'}"]

Object waitForObject(objectOrName)函数等待识别的对象准备好（可见且可用），然后返回其对象的引用。

总的来说，最好使用符号名，因为它们在面对AUT变化时更为稳健，因为我们只需要更新对象映射而不是我们的测试脚本代码，如果对象的属性发生变化。（注意：对于大多数GUI工具包，在使用真实名称时，type属性是强制性的。）

构造函数、函数和属性

Squish对象与脚本语言的本地对象无缝集成。这意味着您可以使用标准语言特性来构造包装类型对象的实例，调用成员函数，获取、设置和遍历这些对象上的属性。

以下是一些简单示例

# create an object of type QPoint
point = QPoint(10, 20)

# read a widget's width property
width = widget.width

# set widget's y-coordinate property
widget.y = 240

# call a member function
widget.setWindowTitle("My Widget")

# call a static function
QApplication.setOverrideCursor(Qt.WaitCursor)

// create an object of type QPoint
var point = new QPoint(10, 20);

// read a widget's width property
var width = widget.width;

// set widget's y-coordinate property
widget.y = 240;

// call a member function
widget.setWindowTitle("My Widget");

// call a static function
QApplication.setOverrideCursor(Qt.WaitCursor);

# create an object of type QPoint
my $point = new QPoint(10, 20);

# read a widget's width property
my $width = widget->width;

# set widget's y-coordinate property
$widget->y(240);

# call a member function
$widget->setWindowTitle("My Widget");

# call a static function
QApplication::setOverrideCursor(Qt::WaitCursor);

# create an object of type QPoint
point = QPoint.new(10, 20)

# read a widget's width property
width = widget.width

# set widget's y-coordinate property
widget.y = 240

# call a member function
widget.setWindowTitle("My Widget")

# call a static function
QApplication.setOverrideCursor(Qt::WAIT_CURSOR)

# create an object of type QPoint
set point [construct QPoint 10 20]

# read a widget's width property
set width [property get $widget width]

# set widget's y-coordinate property
property set $widget y 240

# call a member function
invoke $widget setWindowTitle "My Widget"

# call a static function
invoke QApplication setOverrideCursor [enum Qt WaitCursor]

对于Tcl，我们必须使用enum函数获取枚举值。（参见Tcl笔记。）

函数和属性（macOS）

脚本语言API中的函数名遵循以下约定：选择器名称中的每个冒号（:）都替换为下划线（_）。例如，+stringWithCString:encoding:选择器变为脚本函数stringWithCString_encoding_（注意函数结尾的下划线）。

以下是一些示例，以说明用法。

# create an object of type NSString and initialize it with a value
s = NSString.stringWithUTF8String_("Ambient")

# read an object's intValue property
n = acontrol.intValue

# set an object's intValue property
acontrol.intValue = 33

# call an instance method
s.characterAtIndex_(1)

# call a class method
s = NSString.stringWithCString_encoding_("Zenith", 4)

// create an object of type NSString and initialize it with a value
var s = NSString.stringWithUTF8String_("Ambient");

// read an object's intValue property
var n = acontrol.intValue;

// set an object's intValue property
acontrol.intValue = 33;

// call an instance method
s.characterAtIndex_(1);

// call a class method
s = NSString.stringWithCString_encoding_("Zenith", 4);

# create an object of type NSString and initialize it with a value
my $s = NSString::stringWithUTF8String_("Ambient");

# read an object's intValue property
my $n = $acontrol->intValue;

# set an object's intValue property
$acontrol->intValue(33);

# call an instance method
$s->characterAtIndex_(1);

# call a class method
$s = NSString::stringWithCString_encoding_("Zenith", 4);

# create an object of type NSString and initialize it with a value
s = NSString.stringWithUTF8String_("Ambient");

# read an object's intValue property
n = acontrol.intValue

# set an object's intValue property
acontrol.intValue = 33

# call an instance method
s.characterAtIndex_(1)

# call a class method
s = NSString.stringWithCString_encoding_("Zenith", 4)

# create an object of type NSString and initialize it with a value
set s [invoke NSString stringWithUTF8String_ "Ambient"]

# read an object's intValue property
set n [property get $acontrol intValue]

# set an object's intValue property
property set $acontrol intValue 33

# call an instance method
invoke $s characterAtIndex_ 1

# call a class method
set s [invoke NSString stringWithCString_encoding_ "Zenith" 4]

对象访问函数

Object findObject(objectName)

此函数通过指定的符号名或真实（多属性）名 objectName 查找并返回（对象引用），如果找不到此类对象则抛出 LookupError 异常。该名称也可以是本地脚本字典（或哈希）值。此函数最适合用于不可见对象。对于可见对象，最好使用 Object waitForObject(objectOrName) 函数。

SequenceOfObjects findAllObjects(objectName)

此函数通过指定的符号名或真实（多属性）名 objectName 查找并返回对象引用的列表。因为它可以返回多个对象引用，所以名称中不能包含发生属性。该名称也可以是本地脚本字典（或哈希）值。

SequenceOfObjects object.children(object)

此函数接受一个 object 引用（由 Object findObject(objectName) 函数或 Object waitForObject(objectOrName) 函数返回），并返回该对象的子对象列表。返回类型根据脚本语言而定，例如 Python 中的元组，其他语言中的数组。下面是示例。

依赖于此列表中遇到的子对象顺序的测试用例，可能会发现由于许多不同的因素（例如

• Squish 的增强功能
• 工具包库的更新
• AUT 的变化

obj = waitForObject(":MyWidget")
children = object.children(obj)
# iterate over tuple
for child in children:
    ...

var obj = waitForObject(":MyWidget");
var children = object.children(obj);
// iterate over array
for (var i = 0; i < children.length; ++i) {
    var child = children[i];
    ...
}

my $obj = waitForObject(":MyWidget");
my @children = object::children($obj);
# iterate over array
foreach $child (@children) {
    ...
}

obj = waitForObject(":MyWidget")
children = Squish::Object.children(obj)
# iterate over array
for child in children
    # ...
end

set obj [waitForObject ":MyWidget"]
set children [object children $obj]
foreach child $children {
    ...
}

Object object.convertTo(object, typeName)

此函数将给定的 object 转换为 typeName 字符串指定的类型对象。（可以使用 Object waitForObject(objectOrName) 函数或 Object findObject(objectName) 函数获取适当的对象。）例如

font = object.convertTo(variant, "QFont")

在此示例中，如果 variant 是 QVariant 类型的变量并包含一个 QFont 对象，则返回底层 QFont 对象。如果 object 无效或为空或 typeName 不可识别或转换不可行（例如从 QFont 到 int），则将引发可捕获的异常。

此函数还可以进行其他类型的转换，例如 int 到 String。另请参阅 Object cast(object, type) 函数，它可以用于向下转换（这是 object.convertTo 所不能做的）。

Object object.createNull(type)

此函数创建一个指定 type 类型的空指针或对象。

widget = object.createNull(QWidget)

Boolean object.exists(objectName)

如果存在具有符号名或真实（多属性）名 objectName 的对象，则此函数返回一个真值；否则返回一个假值。该名称也可以是本地脚本字典（或哈希）值。

如果您知道某个特定对象存在，并且只想访问它（例如，检查其属性或对其执行操作），则如果对象是可见的，请使用 Object waitForObject(objectOrName) 函数；如果对象是隐藏的，则使用 Object findObject(objectName) 函数。

Object object.parent(object)

此函数接受一个 object 引用（由 Object findObject(objectName) 函数或 Object waitForObject(objectOrName) 函数返回），并返回父对象。

如果给定对象没有父对象，则该函数返回一个空值 - 具体的类型取决于脚本语言（例如，Python 中的 None，JavaScript 中的 null，Ruby 中的 nil 等）。

KeyValueMap object.properties(object)

此函数接受一个 object 引用（由 Object findObject(objectName) 函数或 Object waitForObject(objectOrName) 函数返回），并返回一个键值映射，其中包含该对象的全部属性。键是属性名，值是属性值。返回类型特定于脚本语言，例如 Python 的 dict，JavaScript 的对象，或 Perl 的 hash。以下提供了示例。

对于 Tcl，数据将写入一个数组，其名称必须作为附加参数给出。除非在每次使用前调用 array unset，否则不应在第二次或随后的调用中使用同一个数组。

widget = waitForObject(":MyWidget")
properties = object.properties(widget)
# Best to use .iteritems(), .iterkeys(), or .itervalues() in Python 2
for name, value in properties.iteritems():
    test.log("%s = %s" % (name, value))

var widget = waitForObject(":MyWidget");
var properties = object.properties(widget);
for (var name in properties) {
    test.log(name + " = " + properties[name]);
}

my $widget = waitForObject(":MyWidget");
my %properties = object::properties($widget);
while (($name, $value) = each(%properties)) {
    test::log("$name = $value");
}

widget = waitForObject(":MyWidget")
properties = Squish::Object.properties(widget)
properties.each {|key, value| Test.log("#{key} = #{value}")}

set widget [waitForObject ":MyWidget"]
object properties $widget properties
foreach key [array names properties] {
    set value [toString $properties($key)]
    test log "$key = $value"
}

ScreenRectangle object.globalBounds(object)

此函数接受一个 object 引用（由 Object findObject(objectName) 函数或 Object waitForObject(objectOrName) 函数返回），并返回对象的屏幕坐标边界矩形，作为 ScreenRectangle 对象。

这些值与 Squish 在对象高亮时使用的值相同。然而，这些值可能不等于工具包特定的几何信息，因为 Squish 可能进一步限制全局边界矩形，以便仅包含实际屏幕上可见的内容（即如果对象的一部分被其父对象剪裁掉）。

var obj = waitForObject(":MyWidget");
var rect = object.globalBounds(obj);
test.verify(rect.width > 200);

y $obj = waitForObject(":MyWidget");
my $rect = object::globalBounds($obj);
test::verify($rect->width > 200);

obj = waitForObject(":MyWidget")
rect = object.globalBounds(obj)
test.verify(rect.width > 200)

obj = waitForObject(":MyWidget")
rect = Squish::Object.globalBounds(obj)
Test.verify(rect.width > 200)

set obj [waitForObject ":MyWidget"]
set rect [object globalBounds $obj]
test verify [expr [property get $rect width] > 200]

Image object.grabScreenshot(object, [parameterMap])

此函数接受一个 object 引用（由 Object findObject(objectName) 函数或 Object waitForObject(objectOrName) 函数返回），并返回其当前可视为 Image Object 对象的截图。

可以通过通过可选的 parameterMap 参数传递的条目配置截图行为。

• delay - 在抓取截图之前的时间延迟（以毫秒为单位）。默认值为 1000（1秒），以允许 AUT 对最新输入做出反应，并在抓取截图之前达到稳定状态。将其减少到 0 可能有助于提高测试执行时间，尤其是在一系列连续的 grabScreenshot() 调用的情况下。

var obj = waitForObject(":MyWidget");
var img = object.grabScreenshot(obj, {delay: 0});
test.attachImage(img);

y $obj = waitForObject(":MyWidget");
my $img = object::grabScreenshot($obj, {"delay" => 0});
test::attachImage($img);

obj = waitForObject(":MyWidget")
img = object.grabScreenshot(obj, {"delay": 0})
test.attachImage(img)

obj = waitForObject(":MyWidget")
img = Squish::Object.grabScreenshot(obj, {"delay" => 0})
Test.attachImage(img)

set obj [waitForObject ":MyWidget"]
set img [object grabScreenshot $obj {delay 0}]
test attachImage $img

—已弃用— QImage grabWidget(object)

此函数抓取 object 窗口（或小部件）的截图，并将其作为 QImage 对象 返回。

SequenceOfObjects 对象.topLevelObjects()

此函数返回 AUT 中所有顶级对象的列表。返回类型取决于脚本语言，例如，在 Python 中为元组，在其他语言中为数组。以下给出了示例。

topLevels = object.topLevelObjects()
# iterate over tuple
for obj in topLevels:
    children = object.children(obj)
    ...

var topLevels = object.topLevelObjects();
// iterate over array
for (var i = 0; i < topLevels.length; ++i) {
    var obj = topLevels[i];
    var children = object.children(obj)
    ...
}

my @topLevels = object::topLevelObjects();
# iterate over array
foreach $obj (@topLevels) {
    my @children = object::children(obj)
    ...
}

topLevels = Squish::Object.topLevelObjects()
# iterate over array
for obj in topLevels
    children = Squish::Object.children(obj)
    #...
end

set topLevels [object topLevelObjects]
foreach obj $topLevels {
    set children [object children $obj]
    ...
}

ScreenRectangle findImage(imageFile, [parameterMap], [searchRegion])

此函数将在显示的当前运行的应用程序上搜索存储在 imageFile 中的模板图像。如果成功，返回找到的图像的位置作为 ScreenRectangle。然后可以使用如 mouseClick() 或 tapObject() 的函数在检测到的位置模拟用户交互。

搜索子图像是按从左到右、从上到下的顺序进行的。返回第一个成功的匹配。要选择其他匹配项，请使用以下描述的 occurrence 参数。

将搜索包括桌面在内的所有可用屏幕。至少在Windows和基于X11的系统上是这样。对于在macOS上多屏幕设置中的搜索，请咨询技术支持。

可以通过传递通过可选 parameterMap 参数传入的条目来配置搜索行为。

• occurrence - 出现索引。默认情况下，将返回第一个匹配项（索引为1）。索引值2及以上将选择尽可能多的连续匹配项。
• tolerant - 启用容错图像搜索模式的布尔开关。在此模式下，模板图像与桌面截图之间的某些差异是可以接受的。默认值是 testSettings.imageSearchTolerant 属性的值。
• threshold - 模板图像与桌面截图之间的相关性的阈值，以百分比表示。相关性高于阈值的认为与模板图像匹配。此参数的有效值通常介于 99.0 和 100.0 之间。默认值是 testSettings.imageSearchThreshold 属性的值。如果将 tolerant 参数设置为 false，则忽略此参数。
• multiscale - 启用缩小图像搜索模式的布尔开关。在此模式下，模板图像将扩展为一系列不同大小的图像。随后，这些图像作为图像搜索的模板图像使用。默认值是 testSettings.imageSearchMultiscale 属性的值。如果将 tolerant 参数设置为 false，则忽略此参数。
• minScale - 模板图像系列大小下限，以百分比表示。调整大小后的模板图像大小将介于原始图像大小的 minScale 和 maxScale 之间。默认值是 testSettings.imageSearchMinScale 属性的值。如果将 tolerant 或 multiscale 参数设置为 false，则忽略此参数。
• maxScale 模板图像系列尺寸的上限，以百分比表示。调整后的模板图像尺寸将在原始图像尺寸的 minScale 和 maxScale 之间扩展。默认值是 testSettings.imageSearchMaxScale 属性的值。当 tolerant 或 multiscale 参数设置为 false 时，此参数将被忽略。

# Click on icon.png
mouseClick( findImage("icon.png") )
# Click on second occurrence of icon.png
mouseClick( findImage("icon.png", {"occurrence": 2}) )

// Click on icon.png
mouseClick( findImage("icon.png") );
// Click on second occurrence of icon.png
mouseClick( findImage("icon.png", {"occurrence": 2}) );

# Click on icon.png
mouseClick( findImage("icon.png") );
# Click on second occurrence of icon.png
mouseClick( findImage("icon.png", {"occurrence" => 2}) );

# Click on icon.png
mouseClick( findImage("icon.png") )
# Click on second occurrence of icon.png
mouseClick( findImage("icon.png", {"occurrence" => 2}) )

# Click on icon.png
invoke mouseClick [waitForImage "icon.png"]
# Click on second occurrence of icon.png
invoke mouseClick [waitForImage "icon.png" {occurrence 2 timeout 10000}]

此函数将仅对屏幕内容执行单次检查。如果无法找到子图，将抛出异常。如果以下情况之一成立，调用这个函数是很有用的：a) 几乎可以确定子图的存在；或 b) 需要进行快速的子图存在检查。在其他所有情况下，建议使用 ScreenRectangle waitForImage(imageFile, [parameterMap], [searchRegion]) 函数进行时间无关的查找。

匹配算法执行逐像素的彩色值比较。因此，除非启用容错搜索模式，否则屏幕内容和子图像内容必须完全匹配 100%。

# Click on icon.png
mouseClick( findImage("icon.png", {'tolerant': True,
                                   'threshold': 99.7,
                                   'multiscale': True,
                                   'minScale': 100.0,
                                   'maxScale': 150.0}) )

// Click on icon.png
mouseClick( findImage("icon.png", {tolerant: true,
                                   threshold: 99.7,
                                   multiscale: true,
                                   minScale: 100.0,
                                   maxScale: 150.0}) );

# Click on icon.png
mouseClick( findImage("icon.png", {tolerant => true,
                                   threshold => 99.7,
                                   multiscale => true,
                                   minScale => 100.0,
                                   maxScale => 150.0}) );

# Click on icon.png
mouseClick( findImage("icon.png", {"tolerant" => true,
                                   "threshold" => 99.7,
                                   "multiscale" => true,
                                   "minScale" => 100.0,
                                   "maxScale" => 150.0}) )

# Check whether icon.png is displayed on screen
invoke mouseClick [ findImage "icon.png" {tolerant true \
                                          threshold 99.7 \
                                          multiscale true \
                                          minScale 100.0 \
                                          maxScale 150.0} ]

如果指定了搜索区域作为最后一个参数，则只在与之对应的区域内进行搜索。搜索区域可以是 AUT 对象、一个 ScreenRectangle 对象或此类对象的数组。还可以是一个特殊的字符串值 "all"，在这种情况下，将使用所有顶层对象。

搜索区域还可以是一个 Image Object 对象。在这种情况下，不会捕获新的屏幕截图，而是使用指定的图片。目前尚无法将搜索范围限定在 Image 对象的某个部分；请使用 Image.copy() 来剪切相关部分。

# Find icon.png on the MyWidget object
findImage("icon.png", {}, waitForObject( names.MyWidget ) )

# Find icon.png on multiple objects
findImage("icon.png", {}, [ waitForObject( names.MyWidget ),
                            waitForObject( names.MyOtherWidget ) ] )

# Find icon.png on the left half of the MyWidget object
bounds = object.globalBounds( waitForObject( names.MyWidget ) )
bounds.width = bounds.width / 2
findImage("icon.png", {}, bounds )

# Find icon.png in the specified area
findImage("icon.png", {}, UiTypes.ScreenRectangle( 100, 100, 200, 300 ) )

# Find icon.png on all top-level objects
findImage("icon.png", {}, "all" )

// Find icon.png on the MyWidget object
findImage("icon.png", {}, waitForObject( names.MyWidget ) );

// Find icon.png on multiple objects
findImage("icon.png", {}, [ waitForObject( names.MyWidget ),
                            waitForObject( names.MyOtherWidget ) ] );

// Find icon.png on the left half of the MyWidget object
var bounds = object.globalBounds( waitForObject( names.MyWidget ) );
bounds.width = bounds.width / 2
findImage("icon.png", {}, bounds );

// Find icon.png in the specified area
findImage("icon.png", {}, UiTypes.ScreenRectangle( 100, 100, 200, 300 ) );

// Find icon.png on all top-level objects
findImage("icon.png", {}, "all" );

# Find icon.png on the MyWidget object
findImage("icon.png", {}, waitForObject( names::MyWidget ) );

# Find icon.png on multiple objects
findImage("icon.png", {}, ( waitForObject( names::MyWidget ),
                            waitForObject( names::MyOtherWidget ) ) );

# Find icon.png on the left half of the MyWidget object
my $bounds = object::globalBounds( waitForObject( names::MyWidget ) );
$bounds->width = $bounds->width / 2;
findImage("icon.png", {}, bounds );

# Find icon.png in the specified area
findImage("icon.png", {}, new UiTypes::ScreenRectangle( 100, 100, 200, 300 ) );

# Find icon.png on all top-level objects
findImage("icon.png", {}, "all" )

# Find icon.png on the MyWidget object
findImage("icon.png", {}, waitForObject( names.MyWidget ) );

# Find icon.png on multiple objects
findImage("icon.png", {}, [ waitForObject( names.MyWidget ),
                            waitForObject( names.MyOtherWidget ) ] );

# Find icon.png on the left half of the MyWidget object
bounds = Squish::Object.globalBounds( waitForObject( names.MyWidget ) );
bounds.width = bounds.width / 2
findImage("icon.png", {}, bounds );

# Find icon.png in the specified area
findImage("icon.png", {}, UiTypes::ScreenRectangle.new( 100, 100, 200, 300 ) );

# Find icon.png on all top-level objects
findImage("icon.png", {}, "all" );

# Find icon.png on the MyWidget object
findImage "icon.png" {} [ waitForObject $names::MyWidget ]

# Find icon.png on multiple objects
findImage "icon.png" {} { [ waitForObject $names::MyWidget ],
                          [ waitForObject $names::MyOtherWidget ] }

# Find icon.png on the left half of the MyWidget object
set bounds [object globalBounds [ waitForObject $names::MyWidget ] ]
property set $bounds width [ expr [ property get $bounds width ] / 2 ]
findImage "icon.png" {} $bounds

# Find icon.png in the specified area
findImage "icon.png" {} [ construct ScreenRectangle 100 100 200 300 ]

# Find icon.png on all top-level objects
findImage "icon.png" {} "all"

String getOcrText([parameterMap], [searchRegion])

此函数将执行显示内容的光学字符识别，并返回所有文本行。

OCR 将在组成桌面的所有可用屏幕上执行。至少在 Windows 和基于 X11 的系统上是如此。对于在 macOS 上实现多屏设置的 OCR，请联系技术支持。

可以通过传递通过可选 parameterMap 参数传入的条目来配置搜索行为。

• language - OCR 引擎的语言提示。使用空字符串将使用 OCR 引擎的默认值。默认值是 testSettings.defaultOcrLanguage 属性的值。
• profiles - OCR 引擎特定配置文件名称的数组。此参数仅在支持配置文件的引擎中使用。
• options - 引擎特定选项名称和值的映射。这些选项在加载指定的配置文件后传递给 OCR 引擎。
• scaleFactor - 图像放大因子。在传递给 OCR 引擎之前，源图像通过该因子放大。默认值为 3.5。如果文本使用大字体渲染，可以将其设置为一个较低的值以提高 OCR 性能。

# Get all text using German language hint
test.log( getOcrText( { "language": "German" } ) )

// Get all text using German language hint
test.log( getOcrText( { language: "German" } ) )

# Get all text using German language hint
test::log( getOcrText( { language => "German" } ) )

# Get all text using German language hint
Test.log( getOcrText( { "language" => "German" } ) )

# Get all text using German language hint
test log [ getOcrText { language "German" } ]

如果将搜索区域指定为最后一个参数，则仅在与之对应的区域内执行 OCR。搜索区域可以是 AUT 对象、一个 ScreenRectangle 对象或此类对象的数组。也可以是一个特殊的字符串值 "all"，在这种情况下，将使用所有顶层对象。

搜索区域还可以是一个 Image Object 对象。在这种情况下，不会捕获新的屏幕截图，而是使用指定的图片。目前尚无法将 OCR 范围限定在 Image 对象的某个部分；请使用 Image.copy() 来剪切相关部分。

# Find all text on the MyWidget object
test.log( getOcrText( {}, waitForObject( names.MyWidget ) )

# Find all text on multiple objects
test.log( getOcrText( {}, [ waitForObject( names.MyWidget ),
                            waitForObject( names.MyOtherWidget ) ] ) )

# Find all text on the left half of the MyWidget object
bounds = object.globalBounds( waitForObject( names.MyWidget ) )
bounds.width = bounds.width / 2
test.log( getOcrText( {}, bounds ) )

# Find all text in the specified area
test.log( getOcrText( {}, UiTypes.ScreenRectangle( 100, 100, 200, 300 ) ) )

# Find all text on all top-level objects
test.log( getOcrText( {}, "all" ) )

# Find all text on the MyWidget object
test.log( getOcrText( {}, waitForObject( names.MyWidget ) ) );

// Find all text on multiple objects
test.log( getOcrText( {}, [ waitForObject( names.MyWidget ),
                            waitForObject( names.MyOtherWidget ) ] ) );

// Find all text on the left half of the MyWidget object
var bounds = object.globalBounds( waitForObject( names.MyWidget ) );
bounds.width = bounds.width / 2
test.log( getOcrText( {}, bounds ) );

// Find all text in the specified area
test.log( getOcrText( {}, new UiTypes.ScreenRectangle( 100, 100, 200, 300 ) ) );

// Find all text on all top-level objects
test.log( getOcrText( {}, "all" ) );

# Find all text on the MyWidget object
test::log( getOcrText( {}, waitForObject( names::MyWidget ) ) );

# Find all text on multiple objects
test::log( getOcrText( {}, ( waitForObject( names::MyWidget ),
                            waitForObject( names::MyOtherWidget ) ) ) );

# Find all text on the left half of the MyWidget object
my $bounds = object::globalBounds( waitForObject( names::MyWidget ) );
$bounds->width = $bounds->width / 2;
test::log( getOcrText( {}, bounds ) );

# Find all text in the specified area
test::log( getOcrText( {}, new UiTypes::ScreenRectangle( 100, 100, 200, 300 ) ) );

# Find all text on all top-level objects
test::log( getOcrText( {}, "all" ) )

# Find all text on the MyWidget object
Test.log( getOcrText( {}, waitForObject( names.MyWidget ) ) );

# Find all text on multiple objects
Test.log( getOcrText( {}, [ waitForObject( names.MyWidget ),
                            waitForObject( names.MyOtherWidget ) ] ) );

# Find all text on the left half of the MyWidget object
bounds = Squish::Object.globalBounds( waitForObject( names.MyWidget ) );
bounds.width = bounds.width / 2
Test.log( getOcrText( {}, bounds ) );

# Find all text in the specified area
Test.log( getOcrText( {}, UiTypes::ScreenRectangle.new( 100, 100, 200, 300 ) ) );

# Find all text on all top-level objects
Test.log( getOcrText( {}, "all" ) );

# Find all text on the MyWidget object
test log [ getOcrText {} [ waitForObject $names::MyWidget ] ]

# Find all text on multiple objects
test log [ getOcrText {} { [ waitForObject $names::MyWidget ],
                           [ waitForObject $names::MyOtherWidget ] } ]

# Find all text on the left half of the MyWidget object
set bounds [object globalBounds [ waitForObject $names::MyWidget ] ]
property set $bounds width [ expr [ property get $bounds width ] / 2 ]
test log [ getOcrText {} $bounds ]

# Find all text in the specified area
test log [ getOcrText {} [ construct ScreenRectangle 100 100 200 300 ] ]

# Find all text on all top-level objects
test log [ getOcrText {} "all" ]

ScreenRectangle findOcrText(text, [parameterMap], [searchRegion])

此函数将对显示进行光学字符识别，同时显示当前运行的应用程序，并在结果集中搜索特定文本。它将返回一个与文本位置相对应的 ScreenRectangle 对象。

OCR 将在组成桌面的所有可用屏幕上执行。至少在 Windows 和基于 X11 的系统上是如此。对于在 macOS 上实现多屏设置的 OCR，请联系技术支持。

可以通过传递通过可选 parameterMap 参数传入的条目来配置搜索行为。

• occurrence - 出现索引。默认情况下，将返回第一个文本匹配项（索引为1）。索引值2及以上将选择连续的匹配项，直到可用。
• language - OCR 引擎的语言提示。使用空字符串将使用 OCR 引擎的默认值。默认值是 testSettings.defaultOcrLanguage 属性的值。
• profiles - OCR 引擎特定配置文件名称的数组。此参数仅在支持配置文件的引擎中使用。
• options - 引擎特定选项名称和值的映射。这些选项在加载指定的配置文件后传递给 OCR 引擎。
• scaleFactor - 图像放大因子。在传递给 OCR 引擎之前，源图像通过该因子放大。默认值为 3.5。如果文本使用大字体渲染，可以将其设置为一个较低的值以提高 OCR 性能。

# Click on text
mouseClick( findOcrText( "Test Text" ) )
# Click on text in German
mouseClick( findOcrText( "Test Text", { "language": "German" } ) )

// Click on text
mouseClick( findOcrText( "Test Text" ) );
// Click on text in German
mouseClick( findOcrText( "Test Text", { language: "German" } ) );

# Click on text
mouseClick( findOcrText( "Test Text" ) );
# Click on text in German
mouseClick( findOcrText( "Test Text", { "language" => "German" } ) );

# Click on text
mouseClick( findOcrText( "Test Text" ) )
# Click on text in German
mouseClick( findOcrText( "Test Text", { "language" => "German" } ) )

# Click on text
invoke mouseClick[ findOcrText "Test Text" ]
# Click on text in German
invoke mouseClick[ findOcrText "Test Text" { language "German" } ]

此函数只对屏幕内容执行单个OCR。如果未找到指定的文本，则会抛出异常。调用此函数在以下情况下很有用：a) 文本存在儿乎肯定或b) 需要快速检查是否存在。在其他所有情况下，首选使用 ScreenRectangle waitForOcrText(text, [parameterMap], [searchRegion]) 函数进行时间无关的查找。

如果将搜索区域指定为最后一个参数，则仅在与之对应的区域内执行 OCR。搜索区域可以是 AUT 对象、一个 ScreenRectangle 对象或此类对象的数组。也可以是一个特殊的字符串值 "all"，在这种情况下，将使用所有顶层对象。

搜索区域还可以是一个 Image Object 对象。在这种情况下，不会捕获新的屏幕截图，而是使用指定的图片。目前尚无法将 OCR 范围限定在 Image 对象的某个部分；请使用 Image.copy() 来剪切相关部分。

# Click on text on the MyWidget object
mouseClick( findOcrText( "Click me", {}, waitForObject( names.MyWidget ) )

# Click on text on multiple objects
mouseClick( findOcrText( "Click me", {}, [ waitForObject( names.MyWidget ),
                                                   waitForObject( names.MyOtherWidget ) ] ) )

# Click on text on the left half of the MyWidget object
bounds = object.globalBounds( waitForObject( names.MyWidget ) )
bounds.width = bounds.width / 2
mouseClick( findOcrText( "Click me", {}, bounds ) )

# Click on text in the specified area
mouseClick( findOcrText( "Click me", {}, UiTypes.ScreenRectangle( 100, 100, 200, 300 ) ) )

# Click on text on all top-level objects
mouseClick( findOcrText( "Click me", {}, "all" ) )

# Click on text on the MyWidget object
mouseClick( findOcrText( "Click me", {}, waitForObject( names.MyWidget ) ) );

// Click on text on multiple objects
mouseClick( findOcrText( "Click me", {}, [ waitForObject( names.MyWidget ),
                                                   waitForObject( names.MyOtherWidget ) ] ) );

// Click on text on the left half of the MyWidget object
var bounds = object.globalBounds( waitForObject( names.MyWidget ) );
bounds.width = bounds.width / 2
mouseClick( findOcrText( "Click me", {}, bounds ) );

// Click on text in the specified area
mouseClick( findOcrText( "Click me", {}, new UiTypes.ScreenRectangle( 100, 100, 200, 300 ) ) );

// Click on text on all top-level objects
mouseClick( findOcrText( "Click me", {}, "all" ) );

# Click on text on the MyWidget object
mouseClick( findOcrText( "Click me", {}, waitForObject( names::MyWidget ) ) );

# Click on text on multiple objects
mouseClick( findOcrText( "Click me", {}, ( waitForObject( names::MyWidget ),
                                                   waitForObject( names::MyOtherWidget ) ) ) );

# Click on text on the left half of the MyWidget object
my $bounds = object::globalBounds( waitForObject( names::MyWidget ) );
$bounds->width = $bounds->width / 2;
mouseClick( findOcrText( "Click me", {}, bounds ) );

# Click on text in the specified area
mouseClick( findOcrText( "Click me", {}, new UiTypes::ScreenRectangle( 100, 100, 200, 300 ) ) );

# Click on text on all top-level objects
mouseClick( findOcrText( "Click me", {}, "all" ) )

# Click on text on the MyWidget object
mouseClick( findOcrText( "Click me", {}, waitForObject( names.MyWidget ) ) );

# Click on text on multiple objects
mouseClick( findOcrText( "Click me", {}, [ waitForObject( names.MyWidget ),
                                                   waitForObject( names.MyOtherWidget ) ] ) );

# Click on text on the left half of the MyWidget object
bounds = Squish::Object.globalBounds( waitForObject( names.MyWidget ) );
bounds.width = bounds.width / 2
mouseClick( findOcrText( "Click me", {}, bounds ) );

# Click on text in the specified area
mouseClick( findOcrText( "Click me", {}, UiTypes::ScreenRectangle.new( 100, 100, 200, 300 ) ) );

# Click on text on all top-level objects
mouseClick( findOcrText( "Click me", {}, "all" ) );

# Click on text on the MyWidget object
invoke mouseClick [ findOcrText "Click me" {} [ waitForObject $names::MyWidget ] ]

# Click on text on multiple objects
invoke mouseClick [ findOcrText "Click me" {} { [ waitForObject $names::MyWidget ],
                                                        [ waitForObject $names::MyOtherWidget ] } ]

# Click on text on the left half of the MyWidget object
set bounds [object globalBounds [ waitForObject $names::MyWidget ] ]
property set $bounds width [ expr [ property get $bounds width ] / 2 ]
invoke mouseClick [ findOcrText "Click me" {} $bounds ]

# Click on text in the specified area
invoke mouseClick [ findOcrText "Click me" {} [ construct ScreenRectangle 100 100 200 300 ] ]

# Click on text on all top-level objects
invoke mouseClick [ findOcrText "Click me" {} "all" ]

SequenceOfObjects findAllOcrText(text, [parameterMap], [searchRegion])

此函数将对显示进行光学字符识别，同时显示当前运行的应用程序，并在结果集中搜索特定文本。它将返回一个与指定文本位置相对应的 ScreenRectangle 对象序列。

OCR 将在组成桌面的所有可用屏幕上执行。至少在 Windows 和基于 X11 的系统上是如此。对于在 macOS 上实现多屏设置的 OCR，请联系技术支持。

可以通过传递通过可选 parameterMap 参数传入的条目来配置搜索行为。

• language - OCR 引擎的语言提示。使用空字符串将使用 OCR 引擎的默认值。默认值是 testSettings.defaultOcrLanguage 属性的值。
• profiles - OCR 引擎特定配置文件名称的数组。此参数仅在支持配置文件的引擎中使用。
• options - 引擎特定选项名称和值的映射。这些选项在加载指定的配置文件后传递给 OCR 引擎。
• scaleFactor - 图像放大因子。在传递给 OCR 引擎之前，源图像通过该因子放大。默认值为 3.5。如果文本使用大字体渲染，可以将其设置为一个较低的值以提高 OCR 性能。

# Check whether 'Test Text' is displayed on screen 3 times
test.compare( len( findAllOcrText( "Test Text", { "language": "German" } ) ), 3 )

// Check whether 'Test Text' is displayed on screen 3 times
test.compare( findAllOcrText( "Test Text", { "language": "German" } ).length, 3 )

# Check whether 'Test Text' is displayed on screen 3 times
my @locations = findAllOcrText( "Test Text", { language => "German" } );
test::compare( scalar @locations, 3 )

# Check whether 'Test Text' is displayed on screen 3 times
Test.compare( findAllOcrText( "Test Text", { "language" => "German" } ).length, 3 );

# Check whether 'Test Text' is displayed on screen 3 times
test compare [ llength [ findAllOcrText "Test Text" { language "German" } ] ] 3

如果将搜索区域指定为最后一个参数，则仅在与之对应的区域内执行 OCR。搜索区域可以是 AUT 对象、一个 ScreenRectangle 对象或此类对象的数组。也可以是一个特殊的字符串值 "all"，在这种情况下，将使用所有顶层对象。

搜索区域还可以是一个 Image Object 对象。在这种情况下，不会捕获新的屏幕截图，而是使用指定的图片。目前尚无法将 OCR 范围限定在 Image 对象的某个部分；请使用 Image.copy() 来剪切相关部分。

# Check whether 'Test Text' is displayed on MyWidget 3 times
test.compare( len( findAllOcrText( "Test Text", {}, waitForObject( names.MyWidget ) ) ), 3 )

# Check whether 'Test Text' is displayed on multiple widgets 3 times
test.compare( len( findAllOcrText( "Test Text", {}, [ waitForObject( names.MyWidget ),
                                                               waitForObject( names.MyOtherWidget ) ] ) ), 3 )

# Check whether 'Test Text' is displayed on the left half of the MyWidget object
bounds = object.globalBounds( waitForObject( names.MyWidget ) )
bounds.width = bounds.width / 2
test.compare( len( findAllOcrText( "Test Text", {}, bounds ) ), 3 )

# Check whether 'Test Text' is displayed on the specified area
test.compare( len( findAllOcrText( "Test Text", {}, UiTypes.ScreenRectangle( 100, 100, 200, 300 ) ) ), 3 )

# Check whether 'Test Text' is displayed on all top-level objects
test.compare( len( findAllOcrText( "Test Text", {}, "all" ) ), 3 )

// Check whether 'Test Text' is displayed on MyWidget 3 times
test.compare( findAllOcrText( "Test Text", {}, waitForObject( names.MyWidget ) ).length , 3 )

// Check whether 'Test Text' is displayed on multiple widgets 3 times
test.compare( findAllOcrText( "Test Text", {}, [ waitForObject( names.MyWidget ),
                                                          waitForObject( names.MyOtherWidget ) ] ).length, 3 )

// Check whether 'Test Text' is displayed on the left half of the MyWidget object
bounds = object.globalBounds( waitForObject( names.MyWidget ) )
bounds.width = bounds.width / 2
test.compare( findAllOcrText( "Test Text", {}, bounds ) .length, 3 )

// Check whether 'Test Text' is displayed on the specified area
test.compare( findAllOcrText( "Test Text", {}, UiTypes.ScreenRectangle( 100, 100, 200, 300 ) ).length, 3 )

// Check whether 'Test Text' is displayed on all top-level objects
test.compare( findAllOcrText( "Test Text", {}, "all" ).length, 3 )

# Check whether 'Test Text' is displayed on MyWidget 3 times
my @locations = findAllOcrText( "Test Text", {}, waitForObject( names::MyWidget ) );
test::compare( scalar @locations, 3 )

# Check whether 'Test Text' is displayed on multiple widgets 3 times
my @locations = findAllOcrText( "Test Text", {}, ( waitForObject( names::MyWidget ),
                                                            waitForObject( names::MyOtherWidget ) ) );
test::compare( scalar @locations, 3 )

# Check whether 'Test Text' is displayed on the left half of the MyWidget object
my $bounds = object::globalBounds( waitForObject( names::MyWidget ) );
$bounds->width = $bounds->width / 2;
my @locations = findAllOcrText( "Test Text", {}, $bounds );
test::compare( scalar @locations, 3 )

# Check whether 'Test Text' is displayed on the specified area
my @locations = findAllOcrText( "Test Text", {}, new UiTypes::ScreenRectangle( 100, 100, 200, 300 ) );
test::compare( scalar @locations, 3 )

# Check whether 'Test Text' is displayed on all top-level objects
my @locations = findAllOcrText( "Test Text", {}, "all" );
test::compare( scalar @locations, 3 )

# Check whether 'Test Text' is displayed on MyWidget 3 times
Test.compare( findAllOcrText( "Test Text", {}, waitForObject( names.MyWidget ) ).length, 3 );

# Check whether 'Test Text' is displayed on multiple widgets 3 times
Test.compare( findAllOcrText( "Test Text", {}, [ waitForObject( names.MyWidget ),
                                                          waitForObject( names.MyOtherWidget ) ] ).length, 3 );

# Check whether 'Test Text' is displayed on the left half of the MyWidget object
bounds = Squish::Object.globalBounds( waitForObject( names.MyWidget ) );
bounds.width = bounds.width / 2
Test.compare( findAllOcrText( "Test Text", {}, bounds ).length, 3 );

# Check whether 'Test Text' is displayed on the specified area
Test.compare( findAllOcrText( "Test Text", {}, UiTypes::ScreenRectangle.new( 100, 100, 200, 300 ) ).length, 3 );

# Check whether 'Test Text' is displayed on all top-level objects
Test.compare( findAllOcrText( "Test Text", {}, "all" ).length, 3 );

# Check whether 'Test Text' is displayed on MyWidget 3 times
test compare [ llength [ findAllOcrText "Test Text" {} [ waitForObject $names::MyWidget ] ] ] 3

# Check whether 'Test Text' is displayed on multiple widgets 3 times
test compare [ llength [ findAllOcrText "Test Text" {} { [ waitForObject $names::MyWidget ],
                                                                  [ waitForObject $names::MyOtherWidget ] } ] ] 3

# Check whether 'Test Text' is displayed on the left half of the MyWidget object
set bounds [object globalBounds [ waitForObject $names::MyWidget ] ]
property set $bounds width [ expr [ property get $bounds width ] / 2 ]
test compare [ llength [ findAllOcrText "Test Text" {} $bounds ] ] 3

# Check whether 'Test Text' is displayed on the specified area
test compare [ llength [ findAllOcrText "Test Text" {} [ construct ScreenRectangle 100 100 200 300 ] ] ] 3

# Check whether 'Test Text' is displayed on all top-level objects
test compare [ llength [ findAllOcrText "Test Text" {} "all" ] ] 3

同步函数

Boolean waitFor(condition)

condition 是要评估的代码片段，作为字符串或函数引用传递，并返回布尔值。waitFor 函数循环一次或多次，并在每次迭代中执行 condition 代码并读取其返回值。每次执行后，如果 condition 代码的返回值为 true，则 waitFor 将结束并返回 true。否则，waitFor 函数将执行另一个迭代，即再次执行 condition 代码，并检查其返回值，循环无限期地进行——或者直到 condition 代码返回 true，在这种情况下 waitFor 将结束并返回 true。

此函数设计为快速简单地轮询适用程序中的条件，其中每次 condition 执行都非常短（通常是几秒钟的几分之一），并且总是返回 true 或 false。如果需要将脚本执行同步到适用程序中的某个特定状态，则非常有用。

请参阅 如何创建和使用同步点 中的使用示例。

Boolean waitFor(condition, timeoutMSec)

condition 是要评估的代码片段，作为字符串或函数引用传递，并返回布尔值。waitFor 函数循环一次或多次，并在每次迭代中执行 condition 代码并读取其返回值。每次执行后，如果 condition 代码的返回值为 true，则 waitFor 将结束并返回 true。如果 condition 代码返回 false，则 waitFor 函数检查它已运行的时间是否超过了 timeoutMSec——如果是，则 waitFor 结束并返回 false；否则它将进行另一个迭代，从再次执行 condition 代码开始。

此函数设计为快速简单地轮询适用程序中的条件，其中每次 condition 执行都非常短（通常是几秒钟的几分之一），并且总是返回 true 或 false。如果需要将脚本执行同步到适用程序中的某个特定状态，则非常有用。

请参阅 如何创建和使用同步点 中的使用示例。

ApplicationContext waitForApplicationLaunch()

ApplicationContext waitForApplicationLaunch(timeoutSecs)

等待新的应用程序启动，Squish随后将其钩入。如果钩入成功，则返回一个表示启动的应用程序的 ApplicationContext 对象。这被Squish用于测试脚本，这些脚本访问由AUT启动的多个应用程序。（另见，应用程序上下文。）

可以指定可选参数 timeoutSecs（以秒为单位的整数）来告诉Squish在抛出错误之前应该准备等待应用程序出现的最长时间。如果指定了此值，则它将覆盖squishrunner的默认AUT超时。如果没有指定，则使用squishserver的默认值——这是20秒，除非已更改；请参阅Squish服务器设置对话框。

Object waitForObject(objectOrName)

Object waitForObject(objectOrName, timeoutMSec)

等待直到 objectOrName 对象可访问（即它存在、可见且启用）。如果成功，则返回对象的引用，或者在失败时（即函数超时）抛出一个可捕获的 LookupError 异常。此函数等待由 testSettings.waitForObjectTimeout 属性定义的时间，或如果使用了可选的 timeoutMSec 参数，则等待指定这么多的毫秒。此函数在您想要同步脚本执行时很有用。

给定的名称也可以是本地脚本字典（即哈希）值。

此函数仅适用于可见的（或变得可见的）对象；对于不可见对象，请考虑使用Object waitForObjectExists(name) 函数。如果您只想知道对象是否存在，请使用Boolean object.exists(objectName) 函数。

可以在用户定义的回调函数中对等待的对象进行额外处理。有关详细信息，请参阅waitUntilObjectReady(anObject)。

Object waitForObjectExists(name)

Object waitForObjectExists(name, timeoutMSec)

等待直到由 name 标识的对象存在。给定的名称可以是本地脚本字典（即哈希）值。如果成功，则返回对象的引用，或者在失败时（即函数超时）抛出一个可捕获的 LookupError 异常。该函数等待由 testSettings.waitForObjectTimeout 属性定义的时间，或如果使用了可选的 timeoutMSec 参数，则等待这么多的毫秒。

Object waitForObjectItem(objectOrName, itemOrIndex)

Object waitForObjectItem(objectOrName, itemOrIndex, timeoutMSec)

等待直到 objectOrName 对象可访问（即它存在、可见且启用），并且包含一个由 itemOrIndex 标识且自身可访问的项目。

给定的名称也可以是本地脚本字典（即哈希）值。

此函数通常用于访问容器内部的项目，例如列表、表格和树。

表中的 itemOrIndex 可以是一个 行/列 字符串，例如 "4/21"。在树中，它可以是点 (.) 分隔的路径字符串，例如 Mammals.Felines.Cats。在字符串可能重复出现的列表中，可以通过在非唯一字符串后附加 (_)，然后是项目的出现索引来选择一个特定的项。例如，"itemtext_3" 会检索包含 "itemtext" 字符串的列表中的第三个项。

返回值取决于 Squish 版本

• Java、Qt 和 Windows：返回值是对 item 的引用。（引用可以与其他 Squish 函数一起使用。）
• Web 和其他 Squish 版本：返回值是对 objectOrName（不是项）的引用。

当失败时，即超时时，函数抛出（可捕获的）LookupError 异常。

函数等待由 testSettings.waitForObjectTimeout 属性定义的时间或如果使用了可选的 timeoutMSec 参数，则为那么多毫秒。

可以通过提供用户定义的回调函数在函数返回之前在对象项上进行附加处理。有关详细信息，请参阅 waitUntilObjectItemReady(item)。

ScreenRectangle waitForImage(imageFile, [parameterMap], [searchRegion])

此函数等待指定的 imageFile 在屏幕上出现，通过重复调用 ScreenRectangle findImage(imageFile, [parameterMap], [searchRegion]) 直到达到超时。在成功的情况下，将在屏幕上找到图像的位置作为 ScreenRectangle 返回。可以使用交互函数，如 mouseClick(screenPoint, modifierState, button)、doubleClick(screenPoint, modifierState, button) 或 tapObject(screenPoint, modifierState, button) 来在检测到的位置上点击或轻触。

搜索的行为可以通过传递到可选的 parameterMap（键值对）的附加参数进行定制，其中键可以是以下之一

• interval - 在图像搜索重试之间等待的毫秒数。默认值是 1000（1 秒）。
• timeout - 在报告图像未找到之前搜索图像的时间，以毫秒为单位。默认值是 20000（20 秒）。
• occurrence - 出现索引。默认情况下，将返回第一个匹配项（索引为1）。索引值2及以上将选择尽可能多的连续匹配项。
• tolerant - 启用容错图像搜索模式的布尔开关。在此模式下，模板图像与桌面截图之间的某些差异是可以接受的。默认值是 testSettings.imageSearchTolerant 属性的值。
• threshold - 模板图像与桌面截图之间的相关性的阈值，以百分比表示。相关性高于阈值的认为与模板图像匹配。此参数的有效值通常介于 99.0 和 100.0 之间。默认值是 testSettings.imageSearchThreshold 属性的值。如果将 tolerant 参数设置为 false，则忽略此参数。
• multiscale - 启用缩小图像搜索模式的布尔开关。在此模式下，模板图像将扩展为一系列不同大小的图像。随后，这些图像作为图像搜索的模板图像使用。默认值是 testSettings.imageSearchMultiscale 属性的值。如果将 tolerant 参数设置为 false，则忽略此参数。
• minScale - 模板图像系列大小下限，以百分比表示。调整大小后的模板图像大小将介于原始图像大小的 minScale 和 maxScale 之间。默认值是 testSettings.imageSearchMinScale 属性的值。如果将 tolerant 或 multiscale 参数设置为 false，则忽略此参数。
• maxScale 模板图像系列尺寸的上限，以百分比表示。调整后的模板图像尺寸将在原始图像尺寸的 minScale 和 maxScale 之间扩展。默认值是 testSettings.imageSearchMaxScale 属性的值。当 tolerant 或 multiscale 参数设置为 false 时，此参数将被忽略。

# Click on icon.png
mouseClick(waitForImage("icon.png"))

// Click on icon.png
mouseClick(waitForImage("icon.png"));

# Click on icon.png
mouseClick(waitForImage("icon.png"));

# Click on icon.png
mouseClick(waitForImage("icon.png"))

# Click on icon.png
invoke mouseClick [waitForImage "icon.png"]

默认情况下，此函数将反复抓取屏幕内容，直到成功或直到 20 秒过去。可以通过通过 parameterMap 传递的 timeout 值设置更长时间（或更短时间）的等待期，以毫秒为单位。为了执行单个图像搜索，请使用 ScreenRectangle findImage(imageFile, [parameterMap], [searchRegion]) 函数。

# Click on second icon.png, wait maximum 10 seconds
mouseClick(waitForImage("icon.png", {"occurrence": 2, "timeout": 10000})

// Click on second icon.png, wait maximum 10 seconds
mouseClick(waitForImage("icon.png", {occurrence: 2, timeout: 10000}));

# Click on second icon.png, wait maximum 10 seconds
mouseClick(waitForImage("icon.png", {"occurrence" => 2, "timeout" => 10000}));

# Click on second icon.png, wait maximum 10 seconds
mouseClick(waitForImage("icon.png", {"occurrence" => 2, "timeout" => 10000}))

# Click on second icon.png, wait maximum 10 seconds
invoke mouseClick [waitForImage "icon.png" {occurrence 2 timeout 10000}]

匹配算法执行逐像素的彩色值比较。因此，除非启用容错搜索模式，否则屏幕内容和子图像内容必须完全匹配 100%。

# Click on icon.png, found with tolerance of 99.7
mouseClick(waitForImage("icon.png", {'tolerant': True,
                                     'threshold': 99.7,
                                     'multiscale': True,
                                     'minScale': 100.0,
                                     'maxScale': 150.0})

// Click on icon.png, found with tolerance of 99.7
mouseClick(waitForImage("icon.png", {tolerant: true,
                                     threshold: 99.7,
                                     multiscale: true,
                                     minScale: 100.0,
                                     maxScale: 150.0}));

# Click on icon.png, found with tolerance of 99.7
mouseClick(waitForImage("icon.png", {tolerant => true,
                                     threshold => 99.7,
                                     multiscale => true,
                                     minScale => 100.0,
                                     maxScale => 150.0}));

# Click on icon.png, found with tolerance of 99.7
mouseClick(waitForImage("icon.png", {"tolerant" => true,
                                     "threshold" => 99.7,
                                     "multiscale" => true,
                                     "minScale" => 100.0,
                                     "maxScale" => 150.0}))

# Click on icon.png, found with tolerance of 99.7
invoke mouseClick [waitForImage "icon.png" {tolerant true \
                                            threshold 99.7 \
                                            multiscale true \
                                            minScale 100.0 \
                                            maxScale 150.0}]

如果指定了搜索区域作为最后一个参数，则只在与之对应的区域内进行搜索。搜索区域可以是 AUT 对象、一个 ScreenRectangle 对象或此类对象的数组。还可以是一个特殊的字符串值 "all"，在这种情况下，将使用所有顶层对象。

搜索区域也可以是图像对象对象。在这种情况下不会捕获新的截图，而是使用指定的图像。目前无法将搜索范围限制在图像对象的一个部分内；请使用Image.copy()来剪切相关部分。由于作为搜索区域的图像对象不可能随时间改变，因此该函数不会重复执行图像搜索，并将立即返回结果。

# Find icon.png on the MyWidget object
waitForImage("icon.png", {}, waitForObject( names.MyWidget ) )

# Find icon.png on multiple objects
waitForImage("icon.png", {}, [ waitForObject( names.MyWidget ),
                               waitForObject( names.MyOtherWidget ) ] )

# Find icon.png on the left half of the MyWidget object
bounds = object.globalBounds( waitForObject( names.MyWidget ) )
bounds.width = bounds.width / 2
waitForImage("icon.png", {}, bounds )

# Find icon.png in the specified area
waitForImage("icon.png", {}, UiTypes.ScreenRectangle( 100, 100, 200, 300 ) )

# Find icon.png on all top-level objects
waitForImage("icon.png", {}, "all" )

// Find icon.png on the MyWidget object
waitForImage("icon.png", {}, waitForObject( names.MyWidget ) );

// Find icon.png on multiple objects
waitForImage("icon.png", {}, [ waitForObject( names.MyWidget ),
                               waitForObject( names.MyOtherWidget ) ] );

// Find icon.png on the left half of the MyWidget object
var bounds = object.globalBounds( waitForObject( names.MyWidget ) );
bounds.width = bounds.width / 2
waitForImage("icon.png", {}, bounds );

// Find icon.png in the specified area
waitForImage("icon.png", {}, UiTypes.ScreenRectangle( 100, 100, 200, 300 ) );

// Find icon.png on all top-level objects
waitForImage("icon.png", {}, "all" );

# Find icon.png on the MyWidget object
waitForImage("icon.png", {}, waitForObject( names::MyWidget ) );

# Find icon.png on multiple objects
waitForImage("icon.png", {}, ( waitForObject( names::MyWidget ),
                               waitForObject( names::MyOtherWidget ) ) );

# Find icon.png on the left half of the MyWidget object
my $bounds = object::globalBounds( waitForObject( names::MyWidget ) );
$bounds->width = $bounds->width / 2;
waitForImage("icon.png", {}, bounds );

# Find icon.png in the specified area
waitForImage("icon.png", {}, new UiTypes::ScreenRectangle( 100, 100, 200, 300 ) );

# Find icon.png on all top-level objects
waitForImage("icon.png", {}, "all" )

# Find icon.png on the MyWidget object
waitForImage("icon.png", {}, waitForObject( names.MyWidget ) );

# Find icon.png on multiple objects
waitForImage("icon.png", {}, [ waitForObject( names.MyWidget ),
                               waitForObject( names.MyOtherWidget ) ] );

# Find icon.png on the left half of the MyWidget object
bounds = Squish::Object.globalBounds( waitForObject( names.MyWidget ) );
bounds.width = bounds.width / 2
waitForImage("icon.png", {}, bounds );

# Find icon.png in the specified area
waitForImage("icon.png", {}, UiTypes::ScreenRectangle.new( 100, 100, 200, 300 ) );

# Find icon.png on all top-level objects
waitForImage("icon.png", {}, "all" );

# Find icon.png on the MyWidget object
waitForImage "icon.png" {} [ waitForObject $names::MyWidget ]

# Find icon.png on multiple objects
waitForImage "icon.png" {} { [ waitForObject $names::MyWidget ],
                             [ waitForObject $names::MyOtherWidget ] }

# Find icon.png on the left half of the MyWidget object
set bounds [object globalBounds [ waitForObject $names::MyWidget ] ]
property set $bounds width [ expr [ property get $bounds width ] / 2 ]
waitForImage "icon.png" {} $bounds

# Find icon.png in the specified area
waitForImage "icon.png" {} [ construct ScreenRectangle 100 100 200 300 ]

# Find icon.png on all top-level objects
waitForImage "icon.png" {} "all"

ScreenRectangle waitForOcrText(text, [parameterMap], [searchRegion])

此函数将对显示进行光学字符识别，同时显示当前运行的应用程序，并在结果集中搜索特定文本。它将返回一个与文本位置相对应的 ScreenRectangle 对象。

OCR 将在组成桌面的所有可用屏幕上执行。至少在 Windows 和基于 X11 的系统上是如此。对于在 macOS 上实现多屏设置的 OCR，请联系技术支持。

可以通过传递通过可选 parameterMap 参数传入的条目来配置搜索行为。

• interval - OCR 搜索重试之间的最小毫秒数。默认值为 1000（1秒）。不同 OCR 尝试之间的实际间隔取决于 OCR 引擎的性能，可能会显著更长。
• timeout - 搜索指定文本并在报告找不到文本之前的时间（毫秒数）。默认值为 20000（20秒）。
• occurrence - 出现索引。默认情况下，将返回第一个文本匹配项（索引为1）。索引值2及以上将选择连续的匹配项，直到可用。
• language - OCR 引擎的语言提示。使用空字符串将使用 OCR 引擎的默认值。默认值是 testSettings.defaultOcrLanguage 属性的值。
• profiles - OCR 引擎特定配置文件名称的数组。此参数仅在支持配置文件的引擎中使用。
• options - 引擎特定选项名称和值的映射。这些选项在加载指定的配置文件后传递给 OCR 引擎。
• scaleFactor - 图像放大因子。在传递给 OCR 引擎之前，源图像通过该因子放大。默认值为 3.5。如果文本使用大字体渲染，可以将其设置为一个较低的值以提高 OCR 性能。

# Click on second 'Hier klicken' occurrence, wait maximum 10 seconds
mouseClick(waitForOcrText("Hier klicken", {"occurrence": 2, "language": "German"})

// Click on second 'Hier klicken' occurrence, wait maximum 10 seconds
mouseClick(waitForOcrText("Hier klicken", {occurrence: 2, language: "German"}));

# Click on second 'Hier klicken' occurrence, wait maximum 10 seconds
mouseClick(waitForOcrText("Hier klicken", {"occurrence" => 2, "language" => "German"}));

# Click on second 'Hier klicken' occurrence, wait maximum 10 seconds
mouseClick(waitForOcrText("Hier klicken", {"occurrence" => 2, "language" => "German"}))

# Click on second 'Hier klicken' occurrence, wait maximum 10 seconds
invoke mouseClick [waitForOcrText "Hier klicken" {occurrence 2 language "German"}]

默认情况下，此函数将反复捕获屏幕内容，直到成功或直到20秒过去。可以通过传递到 parameterMap 的 timeout 值来设置较长的（或较短的）等待时间（毫秒）。为了执行一次 OCR 搜索，请使用ScreenRectangle findOcrText(text, [parameterMap], [searchRegion])函数。

# Click on second 'Click me' occurrence, wait maximum 10 seconds
mouseClick(waitForOcrText("Click me", {"occurrence": 2, "timeout": 10000})

// Click on second 'Click me' occurrence, wait maximum 10 seconds
mouseClick(waitForOcrText("Click me", {occurrence: 2, timeout: 10000}));

# Click on second 'Click me' occurrence, wait maximum 10 seconds
mouseClick(waitForOcrText("Click me", {"occurrence" => 2, "timeout" => 10000}));

# Click on second 'Click me' occurrence, wait maximum 10 seconds
mouseClick(waitForOcrText("Click me", {"occurrence" => 2, "timeout" => 10000}))

# Click on second 'Click me' occurrence, wait maximum 10 seconds
invoke mouseClick [waitForOcrText "Click me" {occurrence 2 timeout 10000}]

如果将搜索区域指定为最后一个参数，则仅在与之对应的区域内执行 OCR。搜索区域可以是 AUT 对象、一个 ScreenRectangle 对象或此类对象的数组。也可以是一个特殊的字符串值 "all"，在这种情况下，将使用所有顶层对象。

搜索区域也可以是图像对象对象。在这种情况下不会捕获新的截图，而是使用指定的图像。目前无法将 OCR 范围限制在图像对象的一个部分内；请使用Image.copy()来剪切相关部分。由于作为搜索区域的图像对象不可能随时间改变，此函数不会重复执行 OCR 并将立即返回结果。

# Click on text on the MyWidget object
mouseClick( waitForOcrText( "Click me", {}, waitForObject( names.MyWidget ) )

# Click on text on multiple objects
mouseClick( waitForOcrText( "Click me", {}, [ waitForObject( names.MyWidget ),
                                              waitForObject( names.MyOtherWidget ) ] ) )

# Click on text on the left half of the MyWidget object
bounds = object.globalBounds( waitForObject( names.MyWidget ) )
bounds.width = bounds.width / 2
mouseClick( waitForOcrText( "Click me", {}, bounds ) )

# Click on text in the specified area
mouseClick( waitForOcrText( "Click me", {}, UiTypes.ScreenRectangle( 100, 100, 200, 300 ) ) )

# Click on text on all top-level objects
mouseClick( waitForOcrText( "Click me", {}, "all" ) )

# Click on text on the MyWidget object
mouseClick( waitForOcrText( "Click me", {}, waitForObject( names.MyWidget ) ) );

// Click on text on multiple objects
mouseClick( waitForOcrText( "Click me", {}, [ waitForObject( names.MyWidget ),
                                              waitForObject( names.MyOtherWidget ) ] ) );

// Click on text on the left half of the MyWidget object
var bounds = object.globalBounds( waitForObject( names.MyWidget ) );
bounds.width = bounds.width / 2
mouseClick( waitForOcrText( "Click me", {}, bounds ) );

// Click on text in the specified area
mouseClick( waitForOcrText( "Click me", {}, new UiTypes.ScreenRectangle( 100, 100, 200, 300 ) ) );

// Click on text on all top-level objects
mouseClick( waitForOcrText( "Click me", {}, "all" ) );

# Click on text on the MyWidget object
mouseClick( waitForOcrText( "Click me", {}, waitForObject( names::MyWidget ) ) );

# Click on text on multiple objects
mouseClick( waitForOcrText( "Click me", {}, ( waitForObject( names::MyWidget ),
                                              waitForObject( names::MyOtherWidget ) ) ) );

# Click on text on the left half of the MyWidget object
my $bounds = object::globalBounds( waitForObject( names::MyWidget ) );
$bounds->width = $bounds->width / 2;
mouseClick( waitForOcrText( "Click me", {}, bounds ) );

# Click on text in the specified area
mouseClick( waitForOcrText( "Click me", {}, new UiTypes::ScreenRectangle( 100, 100, 200, 300 ) ) );

# Click on text on all top-level objects
mouseClick( waitForOcrText( "Click me", {}, "all" ) )

# Click on text on the MyWidget object
mouseClick( waitForOcrText( "Click me", {}, waitForObject( names.MyWidget ) ) );

# Click on text on multiple objects
mouseClick( waitForOcrText( "Click me", {}, [ waitForObject( names.MyWidget ),
                                              waitForObject( names.MyOtherWidget ) ] ) );

# Click on text on the left half of the MyWidget object
bounds = Squish::Object.globalBounds( waitForObject( names.MyWidget ) );
bounds.width = bounds.width / 2
mouseClick( waitForOcrText( "Click me", {}, bounds ) );

# Click on text in the specified area
mouseClick( waitForOcrText( "Click me", {}, UiTypes::ScreenRectangle.new( 100, 100, 200, 300 ) ) );

# Click on text on all top-level objects
mouseClick( waitForOcrText( "Click me", {}, "all" ) );

# Click on text on the MyWidget object
invoke mouseClick [ waitForOcrText "Click me" {} [ waitForObject $names::MyWidget ] ]

# Click on text on multiple objects
invoke mouseClick [ waitForOcrText "Click me" {} { [ waitForObject $names::MyWidget ],
                                                   [ waitForObject $names::MyOtherWidget ] } ]

# Click on text on the left half of the MyWidget object
set bounds [object globalBounds [ waitForObject $names::MyWidget ] ]
property set $bounds width [ expr [ property get $bounds width ] / 2 ]
invoke mouseClick [ waitForOcrText "Click me" {} $bounds ]

# Click on text in the specified area
invoke mouseClick [ waitForOcrText "Click me" {} [ construct ScreenRectangle 100 100 200 300 ] ]

# Click on text on all top-level objects
invoke mouseClick [ waitForOcrText "Click me" {} "all" ]

交互函数

doubleClick(screenPoint, modifierState, button)

doubleClick(screenRectangle, modifierState, button)

此函数在由screenPoint指定的位置或在由screenRectangle指定的矩形的中心执行鼠标双击。这两个位置都在屏幕全局坐标中。可选的modifierState和button参数指定在点击时按下的键盘修饰符和鼠标按钮。请参阅Squish API 函数参数，以获取有效的modifierState和button值的列表。

keyPress(key)

此函数执行指定key键盘键的按键。此key参数是单个字符或写在尖括号之间的特殊键，例如，对于控制键为"<Ctrl>"，对于转换键为"<Alt>"，对于转换键为"<Shift>"，对于回车键为"<Return>"，对于制表键为"<Tab>"。

keyRelease(key)

此函数执行指定key键盘键的释放。此key参数是单个字符或写在尖括号之间的特殊键，请参阅keyPress(key)。

mouseClick(screenPoint, modifierState, button)

mouseClick(screenRectangle, modifierState, button)

该函数在由 screenPoint 指定的位置或由 screenRectangle 指定矩形的中心位置上执行鼠标点击。这两个位置都在屏幕全局坐标中。可选的 modifierState 和 button 参数指定了点击时按下的键盘修饰符和鼠标按钮。有关有效的修饰符状态和按钮值的列表，请参阅 Squish API 函数参数。

mouseMove(x, y)

mouseMove(objectOrName)

mouseMove(objectOrName, x, y)

如果指定了 objectOrName，此函数将鼠标移动到相对于该小部件顶部左边的 x 和 y 位置，否则相对于当前屏幕。

如果没有指定坐标，鼠标将移动到 objectOrName 小部件的中间位置。

如果想要触发需要鼠标处于特定位置的事件，此函数非常有用。例如，工具提示通常只在鼠标位于某个区域上方时出现。

mousePress()

mousePress(mouseButton)

mousePress(mouseButton, modifierState)

mousePress(x, y, mouseButton)

mousePress(x, y, mouseButton, modifierState)

mousePress(objectOrName)

mousePress(objectOrName, mouseButton)

mousePress(objectOrName, mouseButton, modifierState)

mousePress(objectOrName, x, y, mouseButton)

mousePress(objectOrName, x, y, mouseButton, modifierState)

此函数执行鼠标点击。所有参数都是可选的，但坐标 (x,y) 必须同时存在或都不存在。

如果提供了 x 和 y 坐标，则按下操作将在这些坐标处执行，或者在指定了 objectOrName 对象的情况下相对于该对象执行，否则相对于当前屏幕。如果没有提供坐标，则按下操作将在选择有 objectOrName 对象的情况下在对象中间执行，否则在鼠标当前位置执行。

默认情况下使用 MouseButton.LeftButton，但可以通过指定可选的 mouseButton 参数来更改。同样，使用无修饰符的默认修饰符状态，但可以通过指定 modifierState 参数来更改。有关 mouseButton 参数和 modifierState 参数的有效值的详细信息，请参阅 Squish API 函数参数。

此函数有一个特定于工具包的版本，可能具有不同的参数： mousePress()（Windows）。

mouseRelease()

mouseRelease(mouseButton)

mouseRelease(mouseButton, modifierState)

mouseRelease(x, y, mouseButton)

mouseRelease(x, y, mouseButton, modifierState)

mouseRelease(objectOrName)

mouseRelease(objectOrName, mouseButton)

mouseRelease(objectOrName, mouseButton, modifierState)

mouseRelease(objectOrName, x, y, mouseButton)

mouseRelease(objectOrName, x, y, mouseButton, modifierState)

此函数执行鼠标释放操作。所有参数都是可选的，除非坐标必须同时提供或都不提供。

如果提供了 x 和 y 坐标，释放操作将在这些坐标进行，是相对于指定的 objectOrName 对象的，如果指定了该对象，否则相对于当前屏幕。如果没有提供坐标，则在指定了 objectOrName 对象的情况下，在对象中间进行释放，否则在鼠标所在的位置进行释放。

默认情况下使用 MouseButton.LeftButton，但可以通过指定可选的 mouseButton 参数来更改。同样，使用无修饰符的默认修饰符状态，但可以通过指定 modifierState 参数来更改。有关 mouseButton 参数和 modifierState 参数的有效值的详细信息，请参阅 Squish API 函数参数。

此函数有一个特定于工具包的版本，可能具有不同的参数： mouseRelease() (Windows)。

tapObject(screenPoint, modifierState, button)

tapObject(screenRectangle, modifierState, button)

此函数在 screenPoint 指定的位置或 screenRectangle 指定的矩形的中心执行触摸点击。这两个位置都在屏幕全局坐标中。可选的 modifierState 和 button 参数指定了在点击期间按下的键盘修饰符和鼠标按钮。有关有效 modifierState 和 button 值的列表，请参阅 Squish API 函数参数。

调试函数

str className(object)

此函数返回对象的类名作为字符串。(可以使用 Object waitForObject(objectOrName) 函数或 Object findObject(objectName) 函数获取合适的对象。)

highlightObject(objectOrName, [msec])

此函数通过红色矩形突出显示由 objectOrName 指定的屏幕位置。如果对是否通过 Object waitForObject(objectOrName)、ScreenRectangle waitForImage(imageFile, [parameterMap], [searchRegion]) 和相关函数找到的对象是否是正确的对象有疑问，这种可视化确认可能很有用。

除非有可选的 timeout 参数覆盖，否则红色叠加将在屏幕上保持 3 秒。

Boolean isNull(object)

该函数在对象object为null（例如，C++中的空指针）时返回true值；否则返回false值。（可以使用Object waitForObject(objectOrName)函数或Object findObject(objectName)函数来获取一个合适的对象。）

String typeName(object)

该函数返回对象的类名作为字符串。（可以使用Object waitForObject(objectOrName)函数或Object findObject(objectName)函数来获取一个合适的对象。）对于在测试脚本中创建的对象，这里是它们的实际类型名称。对于小部件和其他应用程序对象，Squish会尝试返回正确的类型名称，如果无法实现，则返回"Squish"的通用对象类型名称"Object"。

JavaScript、Perl、Ruby和Tcl脚本应始终返回正确的类型名称。Python脚本通常对于应用程序对象返回"Object"，但Squish的Python API包括str className(object)函数，该函数返回给定对象的正确类名，无论该对象是在测试脚本中创建的还是应用程序对象。

test.breakpoint()

该函数会导致调试器在本位置停止。

test.attachFile(pathToFile, message)

该函数会将pathToFile引用的文件复制到启动Squish时指定的测试报告目录，并在如果报告生成器支持此功能的情况下创建一个指向文件副本的条目。可选的message允许指定附件的简短描述，并将包含在报告中。

pathToFile可以指定使用绝对路径或相对路径附加的文件。在使用相对路径的情况下，它将被添加到当前正在执行测试的脚本的脚本解释器的当前工作目录。

目前，只有XML3、HTML和JSON报告生成器支持附件。其他生成器可以与test.attachFile一起使用，但只会生成包含附加文件路径和提供的message的正常日志消息。

复制的文件将出现在名为"attachments"的子目录中，该目录位于以测试用例命名的目录内。反之，测试用例目录位于以套件命名的目录内，该目录位于测试报告目录。复制的文件名称将与原始指定文件的文件名相匹配。如果报告中已存在同名文件，将添加一个数字以使文件名唯一。

对于不需要指定测试报告目录但需要文件（如xml2、xml或xmljunit）的报告生成器，您可以在调用squishrunner时指定--resultdir以指定测试报告目录，或者当调用test.attachFile时，Squish将回退到在测试用例执行时在当前正在执行的测试用例中生成附件目录。

test.attachDesktopScreenshot(message)

该函数将从当前活动AUT运行系统的桌面创建屏幕截图并将其存储在测试报告目录中。此外，在测试报告中还会记录一个条目，指示截图文件的路径以及包含指定的message。

屏幕截图将以无损PNG格式保存在与使用test.attachFile(pathToFile, message)函数附加的文件相同的附件子目录下，因此对该报告生成器使用的限制和注释也适用于此函数。

此API是test.attachImage(grabDesktopScreenshot(), message)的简写。

test.attachImage(image, message)

该函数将指定的图像存储在测试报告目录中。此外，在测试报告中还将记录一个条目，其中包含图像文件的路径以及指定的message。

图像将以无损PNG格式保存在与使用test.attachFile(pathToFile, message)函数附加的文件相同的附件子目录下，因此对该报告生成器使用的限制和注释也适用于此函数。

test.startVideoCapture(message)

此函数将在测试应用运行的系统上启动桌面视频捕获。视频文件将成为测试报告的一部分，并使用指定的message记录在测试报告中。message是可选的：如果没有指定，将添加包含应用程序名称的默认消息到报告中。

在脚本中的任何时刻，对于给定应用程序上下文，只有一个视频捕获。在同一应用程序上下文中尝试启动另一个视频捕获将导致错误。

当测试应用终止或断开连接时（无论是通过测试脚本命令还是作为测试用例结束的一部分），将停止视频捕获。如果测试应用意外终止，视频文件可能不完整。

可以在启动后任何时刻使用test.stopVideoCapture(message)显式终止视频捕获。

如果通过--enable-video-capture命令行选项启用了所有应用的视频捕获，则此函数将只在测试报告中添加一个日志消息（另请参阅回放选项 –enable-video-capture）。

test.stopVideoCapture(message)

此函数将在测试应用运行的系统上停止桌面视频捕获。使用指定的message将视频捕获的结束记录在测试报告中。message是可选的：如果没有指定，将添加包含应用程序名称的默认消息到报告中。

尝试在没有任何视频捕获活动的地方停止视频捕获会导致抛出异常。视频捕获是通过test.startVideoCapture(message)启动的，或者通过在命令行上使用--enable-video-capture选项启用（另请参阅回放选项 –enable-video-capture）。

如果通过--enable-video-capture命令行选项启用了所有应用的视频捕获，则此函数将只在测试报告中添加一个日志消息。当应用程序已经终止时，视频捕获将自动终止。

转换函数

Object cast(object, type)

将该object转换为指定的type，并返回该对象或不可变类型的对象的新副本的引用。 （可以使用Object waitForObject(objectOrName)函数或Object findObject(objectName)函数来获取合适的对象。）所需的type可以通过名称（作为字符串）或使用类型对象指定。

对于可变对象，将修改对象本身。

如果转换失败，则返回未更改的对象引用。

此函数可以通过下标转换（例如，从QWidget到QTextEdit）。 有关用法示例，请参阅特定对象的处理程序。 还请参阅Object object.convertTo(object, typeName)函数。

验证函数

比较、验证和异常函数用于将应用于正在运行的AUT的测试结果记录到Squish的测试日志中，作为通过或失败。 其他函数可用于以编程方式将任何类型的测试结果记录到测试日志中。 参见验证点创建视图和如何创建和使用验证点。

grabDesktopScreenshot()

此函数捕获AUT正在运行的屏幕上的图像，并返回一个Image Object。

var img = grabDesktopScreenshot();
test.attachImage(img);

my $img = grabDesktopScreenshot();
test::attachImage($img);

img = grabDesktopScreenshot()
test.attachImage(img)

img = grabDesktopScreenshot()
Test.attachImage(img)

set img [grabDesktopScreenshot]
test attachImage $img

saveDesktopScreenshot(filename)

此函数捕获AUT正在运行的屏幕上的图像，并将其存储在squishide（或squishrunner）正在执行的计算机上。

如果没有指定路径，则文件将存储在squishrunner进程的工作目录中。（squishrunner的默认工作目录是它当前正在执行的测试用例的路径。）

如果指定了相对路径，则相对于squishrunner进程的工作目录。（squishrunner的默认工作目录是它当前正在执行的测试用例的路径。）

如果指定了绝对路径，则直接使用该路径。

文件名应具有表示用于的图像格式的后缀。以下是一个在JavaScript、Python、Ruby和Perl中有效的使用示例

saveDesktopScreenshot("screen.png");

对于Tcl

saveDesktopScreenshot "screen.png"

可用的格式可能会有所不同，但始终至少包括以下格式

• .bmp — Windows位图
• .png — 可便携网络图形
• .ppm — 可便携像素图
• .xbm — X11位图（单色）
• .xpm — X11像素图

此API是调用grabDesktopScreenshot()并随后在结果图像上调用Image.save(fileName)的简写。

saveObjectSnapshot(objectNameOrReference, snapshotImageFile.xml)

此函数捕获一个对象的快照并将它以xml格式保存到指定的文件中。对象快照表示对象的状态，包括所有属性和子对象及其属性。

如果指定了快照的相对路径，它相对于squishrunner进程的工作目录。（squishrunner的默认工作目录是当前执行的测试用例的路径。)

如果指定了绝对路径，则直接使用该路径。

快照中实际保存的内容可以通过修改位于/etc/edition_snapshot_filter.xml（其中<edition>是您正在使用的Squish版本，例如java、qt、web、windows、mac、ios或android）的.xml文件进行定制。使用本功能，您可以排除某些类或类的属性，并决定在输出中包含实际名称或符号名称。

以下是一个在JavaScript、Python、Ruby和Perl中合法使用的示例。

saveObjectSnapshot( objectNameOrReference, "objectSnapshot.xml" );

对于Tcl

saveObjectSnapshot objectNameOrReference "objectSnapshot.xml"

Boolean test.compare(value1, value2)

Boolean test.compare(value1, value2, message)

此函数比较value1和value2，如果它们相等，将在测试日志中添加类型为PASS的测试结果，并返回true值。否则，在测试日志中添加类型为FAIL的测试结果，并返回false值。

如果存在可选的message参数（类型为字符串，例如注释、问题编号或测试计划引用），则无论测试是否通过，它都会添加到测试结果中。

可以使用testSettings.breakOnFailure属性，在验证失败时使调试器停止。

可以使用testSettings.throwOnFailure属性，在验证失败时使此函数引发脚本异常。

Boolean test.exception(code)

Boolean test.exception(code, message)

此函数执行通过字符串code传递的代码，期望它引发异常。如果引发异常，则在测试日志中添加类型为PASS的测试结果，并返回true值；否则，在测试日志中添加类型为FAIL的测试结果，并返回false值。

如果存在可选的message参数（类型为字符串，例如注释、问题编号或测试计划引用），则无论测试是否通过，它都会添加到测试结果中。

可以使用testSettings.breakOnFailure属性，在给定代码没有引发异常的情况下使调试器停止。

可以使用testSettings.throwOnFailure属性，在给定代码没有引发异常的情况下使此函数引发脚本异常。

test.fail(message)

test.fail(message, detail)

此函数无条件地将指定的message字符串（如果有的话，还包括detail字符串）添加到Squish的测试日志中的FAIL条目。

可以使用testSettings.breakOnFailure属性，在此函数处停止调试器。

可以使用testSettings.throwOnFailure属性，使此函数额外地引发脚本异常。

test.fatal(message)

test.fatal(message, detail)

该函数无条件地将具有给定 message 字符串和（如果提供）detail 字符串的 FATAL 条目添加到 Squish 的测试日志中。

可以使用testSettings.breakOnFailure属性，在此函数处停止调试器。

可以使用testSettings.throwOnFailure属性，使此函数额外地引发脚本异常。

test.log(message)

test.log(message, detail)

该函数无条件地将具有给定 message 字符串和（如果提供）detail 字符串的 LOG 条目添加到 Squish 的测试日志中。

test.pass(message)

test.pass(message, detail)

该函数无条件地将具有给定 message 字符串和（如果提供）detail 字符串的 PASS 条目添加到 Squish 的测试日志中。

test.resultCount(resultCategory)

此函数返回当前测试用例给定 resultCategory 的结果数量。必须使用以下字符串之一："errors"，"fails"，"fatals"，"passes"，"testcases"，"tests"，"warnings"，"xfails" 或 "xpasses"。

结果计数仅在当前运行的测试用例上收集。

布尔型 test.verify(condition)

布尔型 test.verify(condition, message)

此函数评估 condition，如果评估为真值（例如，true 或 1），则在测试日志中添加类型为 PASS 的测试结果。否则，在测试日志中添加类型为 FAIL 的结果。在两种情况下，该函数返回评估 condition 的结果（即在 PASS 上为真值，在 FAIL 上为假值）。

如果存在可选的 message 参数（字符串类型——例如，注释、缺陷编号或测试计划引用），无论测试是通过还是失败，都会将其添加到测试结果中。

可以使用testSettings.breakOnFailure属性，在验证失败时使调试器停止。

可以使用testSettings.throwOnFailure属性，在验证失败时使此函数引发脚本异常。

布尔型 test.vp(name)

布尔型 test.vp(name, message)

此函数执行名为 name 的验证点。如果验证点的比较成功，则将类型为 PASS 的测试结果添加到测试日志中，并返回一个真值。否则，将类型为 FAIL 的结果添加到测试日志，并返回一个假值。

如果验证点引用的对象找不到，则该函数将返回一个假值，如果 Squish 被配置为这样做，则可能还会弹出对象未找到对话框。

如果存在可选的 message 参数（字符串类型——例如，注释、缺陷编号或测试计划引用），无论测试是通过还是失败，都会将其添加到测试结果中。

在发生 FAIL 的情况下，除非 squishrunner 被配置为 --abortOnFail，否则测试用例将转到下一个测试语句。

可以使用testSettings.breakOnFailure属性，在验证失败时使调试器停止。

可以使用testSettings.throwOnFailure属性，在验证失败时使此函数引发脚本异常。

布尔型 test.vpWithObject(name, objectNameOrReference)

此函数执行名为name的验证点，此处执行与对象objectNameOrReference的比较，而不是与VP文件中存在的对象进行比较。如果验证点的比较成功，则将类型为PASS的测试结果添加到测试日志，并且此函数返回一个true值。否则，将类型为FAIL的结果添加到测试日志，并返回一个false值。如果VP包含/验证多个对象，test.vpWithObject()将记录一个ERROR。

可以使用testSettings.breakOnFailure属性，在验证失败时使调试器停止。

可以使用testSettings.throwOnFailure属性，在验证失败时使此函数引发脚本异常。

Boolean test.vpWithImage(name, imageOrFilePath)

此函数执行名为name的截图验证点，此处执行与imageOrFilePath的比较，而不是获取验证点文件中指定对象的截图。获得imageOrFilePath可以是Image对象或图像文件的路径。如果验证点的比较成功，则将类型为PASS的测试结果添加到测试日志，并返回一个true值。否则，将类型为FAIL的结果添加到测试日志，并返回一个false值。如果VP包含/验证多个对象或不是截图VP，test.vpWithImage()将记录一个ERROR。

可以使用testSettings.breakOnFailure属性，在验证失败时使调试器停止。

可以使用testSettings.throwOnFailure属性，在验证失败时使此函数引发脚本异常。

test.warning(message)

test.warning(message, detail)

此函数无条件将带有给定message字符串的WARNING条目添加到Squish的测试日志中，如果提供了detail字符串，也可以添加该字符串。

test.skip(message)

test.skip(message, detail)

此函数通过抛出异常并将带有给定message字符串的SKIPPED条目添加到Squish的测试日志中，并如果提供了detail字符串则添加该字符串，来跳过当前脚本测试用例或当前BDD场景的进一步执行（或BDD场景轮廓迭代）。如果测试用例在跳过之前记录了验证失败，则它仍然被视为失败。

Boolean test.xcompare(value1, value2)

Boolean test.xcompare(value1, value2, message)

此函数用于处理测试脚本中的预期失败。用于测试有一天应该修复的错误。

该函数比较value1和value2，如果它们不相等，则在测试日志中添加类型为XFAIL（期望失败）的测试结果并返回一个false值。否则，在测试日志中添加类型为XPASS（意外的PASS）的测试结果并返回一个true值。

“预期失败”结果用于确切知道由于AUT中的错误，比较或验证将现在出错的情况。

在您想要确保属性永远不会具有特定值的测试用例中，我们建议使用test.verify()，或者直接使用if结构与test.fail()一起使用。

如果存在可选的 message 参数（字符串类型——例如，注释、缺陷编号或测试计划引用），无论测试是通过还是失败，都会将其添加到测试结果中。

可以使用testSettings.breakOnFailure属性在验证意外通过时停止调试器。

可以使用testSettings.throwOnFailure属性在验证意外通过时使此函数引发脚本异常。

test.xfail(message)

test.xfail(message, detail)

此函数无条件地将带有指定message字符串的XFAIL（预期的失败）条目添加到Squish的测试日志中，如果提供了detail字符串，也会添加。预期的失败结果适用于已知由于自治程序（AUT）中的错误，比较或验证将立即错误的情况。

test.xpass(message)

test.xpass(message, detail)

此函数无条件地将带有指定message字符串的XPASS（意外的通过）条目添加到Squish的测试日志中，如果提供了detail字符串，也会添加。

布尔测试.test.xverify(condition)

布尔测试.test.xverify(condition, message)

此功能用于在测试脚本中测试预期的失败。用于处理应有一天修复的错误。

该函数评估condition，如果它评估为假值（例如，任何不是true或非零的东西），则将在测试日志中添加类型为XFAIL（预期失败）的测试结果。否则，将添加类型为XPASS（意外通过）的测试结果。在两种情况下，该函数都返回评估condition的结果（即在XFAIL上为假值，在XPASS上为真值）。

如果存在可选的 message 参数（字符串类型——例如，注释、缺陷编号或测试计划引用），无论测试是通过还是失败，都会将其添加到测试结果中。

可以使用testSettings.breakOnFailure属性在验证意外通过时停止调试器。

可以使用testSettings.throwOnFailure属性在验证意外通过时使此函数引发脚本异常。

布尔测试.test.xvp(name)

布尔测试.test.xvp(name, message)

此功能用于测试预期的验证点失败。用于处理应有一天修复的错误。

此功能执行名为name的验证点。如果验证点的比较失败，则将在测试日志中添加类型为XFAIL（预期失败）的测试结果，并返回真值。否则，在测试日志中添加类型为XPASS（意外通过）的结果，并返回假值。

如果验证点引用的对象找不到，则该函数将返回一个假值，如果 Squish 被配置为这样做，则可能还会弹出对象未找到对话框。

如果存在可选的 message 参数（字符串类型——例如，注释、缺陷编号或测试计划引用），无论测试是通过还是失败，都会将其添加到测试结果中。

在XPASS的情况下，除非squishrunner被配置为--abortOnFail，否则测试用例将进入下一个测试语句。

可以使用testSettings.breakOnFailure属性在验证意外通过时停止调试器。

可以使用testSettings.throwOnFailure属性在验证意外通过时使此函数引发脚本异常。

StackTrace test.stackTrace()

StackTrace test.stackTrace(startFrame)

StackTrace test.stackTrace(startFrameIndex, maxFrameCount)

此功能返回一个表示当前活动函数调用的堆栈跟踪的列表。列表中的第一个元素包含有关StackTrace test.stackTrace()调用位置的信息，第二个元素包含调用者的信息，依此类推。列表中的最后一个元素通常是main函数调用。

返回列表中的每个堆栈跟踪值具有两个字段

• fileName：执行函数调用的源文件名称。
• line：执行函数调用的脚本文件中的行号。

如果提供了可选的 startFrameIndex 参数（一个数字），则会跳过最近给定数量的帧。这在从框架函数检索堆栈跟踪时很有用，在这种情况下，堆栈跟踪可能不应该包括框架本身的内部代码。如果没有提供此参数，则默认为零，即不跳过任何帧。

如果同时提供了 startFrameIndex 和 maxFrameCount，则堆栈跟踪将限制在 maxFrameCount 帧内，即不会回溯到对 main 函数的初始调用。这在深层嵌套脚本框架中可以提高性能。

test.fixateResultContext()

test.fixateResultContext(ancestorFrameIndex)

test.restoreResultContext()

这些函数临时强制其他 Squish 函数（如 布尔 test.xcompare(value1, value2) 或 布尔 test.verify(condition)）创建的测试结果将重写其报告条目的位置，以便结果条目的位置不再是 text.xcompare 被调用的位置，而是当前函数的祖先帧中的任何位置。

test.fixateResultContext 函数调整生成测试结果条目时使用的调用堆栈帧；默认情况下，它将重写所有结果条目的位置，使它们看起来是从父堆栈帧发出的。通过传递可选参数 1 可以达到相同的效果。您可以选择其他值来引用其他祖先堆栈帧，例如，2 将引用祖父堆栈帧（调用者的调用者）。

使用 test.restoreResultContext 来撤销之前的 test.fixateResultContext 调用的效果。请注意，调用可以是嵌套的，即，对 fixateResultContext 的多次后续调用需要多次调用 restoreResultContext。

这里有一些示例；请注意，由 test.compare 调用触发的测试结果条目将以指向 main 函数的位置进行记录，而不是指向 libraryFunction 函数。

def libraryFunction():
  test.fixateResultContext(1)
  test.compare("Apples", "Oranges")
  test.restoreResultContext()

def main():
  libraryFunction()

function libraryFunction()
{
  test.fixateResultContext(1);
  test.compare("Apples", "Oranges");
  test.restoreResultContext();
}

function main()
{
  libraryFunction();
}

sub libraryFunction
{
  test::fixateResultContext(1);
  test::compare("Apples", "Oranges");
  test::restoreResultContext();
}

sub main
{
  libraryFunction();
}

require 'squish'

include Squish

def libraryFunction
  Test.fixateResultContext(1)
  Test.compare("Apples", "Oranges")
  Test.restoreResultContext()
end

def main
  libraryFunction()
end

proc libraryFunction {} {
  test fixateResultContext 1
  test compare "Apples" "Oranges"
  test restoreResultContext
}

proc main {} {
  libraryFunction
}

• 当不使用 fixateResultContext/restoreResultContext 时，与比较相关的脚本文件位置。这是默认设置 - 测试结果与相应的 test 语句的位置相关联。
• 使用 fixateResultContext/restoreResultContext 时的比较相关的脚本文件位置，如在此处所示。由于 fixateResultContext 调用，由 test.compare 语句生成的测试结果在调用位置记录，即 libraryFunction 被调用的地方。

布尔 test.imagePresent(imageFile, [parameterMap], [searchRegion])

布尔 test.imageNotPresent(imageFile, [parameterMap], [searchRegion])

此函数将在显示上也显示当前正在运行的应用程序的情况下，对存储在 imageFile 中的模板图像进行搜索。如果成功，则将添加类型为 PASS 的测试结果到测试日志中，并返回 true。否则，将在测试日志中添加类型为 FAIL 的测试结果，并返回 false。

函数的imageNotPresent()变体与imagePresent()完全相同，只不过它等待找到图像的反面情况。它可用于验证图像不存在。

子图像搜索是按从左到右、从上到下的顺序进行的。首先成功的匹配被选中。若要选择其他匹配项，请使用以下描述的occurrence参数。

将搜索包括桌面在内的所有可用屏幕。至少在Windows和基于X11的系统上是这样。对于在macOS上多屏幕设置中的搜索，请咨询技术支持。

可以通过传递通过可选 parameterMap 参数传入的条目来配置搜索行为。

• occurrence - 发生索引。默认情况下将选择第一个匹配项（索引为1）。索引值2及以上将选择连续的匹配项。
• interval - 在图像搜索重试之间等待的毫秒数。默认值是 1000（1 秒）。
• timeout - 在报告图像未找到之前搜索图像的时间，以毫秒为单位。默认值是 20000（20 秒）。
• tolerant - 启用容错图像搜索模式的布尔开关。在此模式下，模板图像与桌面截图之间的某些差异是可以接受的。默认值是 testSettings.imageSearchTolerant 属性的值。
• threshold - 模板图像与桌面截图之间的相关性的阈值，以百分比表示。相关性高于阈值的认为与模板图像匹配。此参数的有效值通常介于 99.0 和 100.0 之间。默认值是 testSettings.imageSearchThreshold 属性的值。如果将 tolerant 参数设置为 false，则忽略此参数。
• multiscale - 启用缩小图像搜索模式的布尔开关。在此模式下，模板图像将扩展为一系列不同大小的图像。随后，这些图像作为图像搜索的模板图像使用。默认值是 testSettings.imageSearchMultiscale 属性的值。如果将 tolerant 参数设置为 false，则忽略此参数。
• minScale - 模板图像系列大小下限，以百分比表示。调整大小后的模板图像大小将介于原始图像大小的 minScale 和 maxScale 之间。默认值是 testSettings.imageSearchMinScale 属性的值。如果将 tolerant 或 multiscale 参数设置为 false，则忽略此参数。
• maxScale 模板图像系列尺寸的上限，以百分比表示。调整后的模板图像尺寸将在原始图像尺寸的 minScale 和 maxScale 之间扩展。默认值是 testSettings.imageSearchMaxScale 属性的值。当 tolerant 或 multiscale 参数设置为 false 时，此参数将被忽略。
• message - 一个可选的详细描述（字符串类型），无论测试是否通过，都会添加到测试结果中，类似于Boolean test.compare(value1, value2)的message参数。

# Verify the icon.png is displayed
test.imagePresent("icon.png")
# Verify the icon.png is displayed at least twice
test.imagePresent("icon.png", {"occurrence": 2})

// Verify the icon.png is displayed
test.imagePresent("icon.png");
// Verify the icon.png is displayed at least twice
test.imagePresent("icon.png", {"occurrence": 2});

# Verify the icon.png is displayed
test::imagePresent("icon.png")
# Verify the icon.png is displayed at least twice
test::imagePresent("icon.png", {"occurrence" => 2})

# Verify the icon.png is displayed
Test.imagePresent("icon.png")
# Verify the icon.png is displayed at least twice
Test.imagePresent("icon.png", {"occurrence" => 2})

# Verify the icon.png is displayed
test imagePresent "icon.png"
# Verify the icon.png is displayed at least twice
test imagePresent "icon.png" {"occurrence": 2}

默认情况下，此函数将反复捕获屏幕内容，直到找到图像或经过20秒。通过parameterMap传入的timeout值可以设置更长的（或更短的）等待时间，单位为毫秒。

匹配算法执行逐像素的彩色值比较。因此，除非启用容错搜索模式，否则屏幕内容和子图像内容必须完全匹配 100%。

# Verify the icon.png is displayed
test.imagePresent( "icon.png", {'tolerant': True,
                                'threshold': 99.7,
                                'multiscale': True,
                                'minScale': 100.0,
                                'maxScale': 150.0})

// Verify the icon.png is displayed
test.imagePresent("icon.png", {tolerant: true,
                               threshold: 99.7,
                               multiscale: true,
                               minScale: 100.0,
                               maxScale: 150.0});

# Verify the icon.png is displayed
test::imagePresent("icon.png", {tolerant => true,
                                threshold => 99.7,
                                multiscale => true,
                                minScale => 100.0,
                                maxScale => 150.0}) );

# Verify the icon.png is displayed
Test.imagePresent("icon.png", {"tolerant" => true,
                               "threshold" => 99.7,
                               "multiscale" => true,
                               "minScale" => 100.0,
                               "maxScale" => 150.0}) )

# Verify the icon.png is displayed
test imagePresent "icon.png" {tolerant true \
                              threshold 99.7 \
                              multiscale true \
                              minScale 100.0 \
                              maxScale 150.0}

如果指定了搜索区域作为最后一个参数，则只在与之对应的区域内进行搜索。搜索区域可以是 AUT 对象、一个 ScreenRectangle 对象或此类对象的数组。还可以是一个特殊的字符串值 "all"，在这种情况下，将使用所有顶层对象。

searchRegion也可以是一个Image Object对象。在这种情况下，不会捕获新的屏幕截图，而是使用指定的图像。目前无法将搜索范围限制为图像的某部分；请使用Image.copy()剪切相关部分。由于用作搜索区域的Image对象不可能随时间变化，此功能不会反复进行图像搜索，将立即返回结果。

# Verify the icon.png is displayed on the MyWidget object
test.imagePresent("icon.png", {}, waitForObject( names.MyWidget ) )

# Verify the icon.png is displayed on multiple objects
test.imagePresent("icon.png", {}, [ waitForObject( names.MyWidget ),
                            waitForObject( names.MyOtherWidget ) ] )

# Verify the icon.png is displayed on the left half of the MyWidget object
bounds = object.globalBounds( waitForObject( names.MyWidget ) )
bounds.width = bounds.width / 2
test.imagePresent("icon.png", {}, bounds )

# Verify the icon.png is displayed in the specified area
test.imagePresent("icon.png", {}, UiTypes.ScreenRectangle( 100, 100, 200, 300 ) )

# Verify the icon.png is displayed on all top-level objects
test.imagePresent("icon.png", {}, "all" )

// Verify the icon.png is displayed on the MyWidget object
test.imagePresent("icon.png", {}, waitForObject( names.MyWidget ) );

// Verify the icon.png is displayed on multiple objects
test.imagePresent("icon.png", {}, [ waitForObject( names.MyWidget ),
                            waitForObject( names.MyOtherWidget ) ] );

// Verify the icon.png is displayed on the left half of the MyWidget object
var bounds = object.globalBounds( waitForObject( names.MyWidget ) );
bounds.width = bounds.width / 2
test.imagePresent("icon.png", {}, bounds );

// Verify the icon.png is displayed in the specified area
test.imagePresent("icon.png", {}, UiTypes.ScreenRectangle( 100, 100, 200, 300 ) );

// Verify the icon.png is displayed on all top-level objects
test.imagePresent("icon.png", {}, "all" );

# Verify the icon.png is displayed on the MyWidget object
test::imagePresent("icon.png", {}, waitForObject( names::MyWidget ) );

# Verify the icon.png is displayed on multiple objects
test::imagePresent("icon.png", {}, ( waitForObject( names::MyWidget ),
                            waitForObject( names::MyOtherWidget ) ) );

# Verify the icon.png is displayed on the left half of the MyWidget object
my $bounds = object::globalBounds( waitForObject( names::MyWidget ) );
$bounds->width = $bounds->width / 2;
test::imagePresent("icon.png", {}, bounds );

# Verify the icon.png is displayed in the specified area
test::imagePresent("icon.png", {}, new UiTypes::ScreenRectangle( 100, 100, 200, 300 ) );

# Verify the icon.png is displayed on all top-level objects
test::imagePresent("icon.png", {}, "all" )

# Verify the icon.png is displayed on the MyWidget object
Test.imagePresent("icon.png", {}, waitForObject( names.MyWidget ) );

# Verify the icon.png is displayed on multiple objects
Test.imagePresent("icon.png", {}, [ waitForObject( names.MyWidget ),
                            waitForObject( names.MyOtherWidget ) ] );

# Verify the icon.png is displayed on the left half of the MyWidget object
bounds = Squish::Object.globalBounds( waitForObject( names.MyWidget ) );
bounds.width = bounds.width / 2
Test.imagePresent("icon.png", {}, bounds );

# Verify the icon.png is displayed in the specified area
Test.imagePresent("icon.png", {}, UiTypes::ScreenRectangle.new( 100, 100, 200, 300 ) );

# Verify the icon.png is displayed on all top-level objects
Test.imagePresent("icon.png", {}, "all" );

# Verify the icon.png is displayed on the MyWidget object
test imagePresent "icon.png" {} [ waitForObject $names::MyWidget ]

# Verify the icon.png is displayed on multiple objects
test imagePresent "icon.png" {} { [ waitForObject $names::MyWidget ],
                                   [ waitForObject $names::MyOtherWidget ] }

# Verify the icon.png is displayed on the left half of the MyWidget object
set bounds [object globalBounds [ waitForObject $names::MyWidget ] ]
property set $bounds width [ expr [ property get $bounds width ] / 2 ]
test imagePresent "icon.png" {} $bounds

# Verify the icon.png is displayed in the specified area
test imagePresent "icon.png" {} [ construct ScreenRectangle 100 100 200 300 ]

# Verify the icon.png is displayed on all top-level objects
test imagePresent "icon.png" {} "all"

布尔测试 Boolean test.ocrTextPresent(text, [parameterMap], [searchRegion])

布尔测试 Boolean test.ocrTextNotPresent(text, [parameterMap], [searchRegion])

此函数将对显示进行光学字符识别，并搜索结果显示集中的特定文本。如果指定文本存在，将在测试日志中添加类型为PASS的测试结果，并且函数返回true。否则，将在测试日志中添加类型为FAIL的测试结果，并且函数返回false。

函数的ocrTextNotPresent()变体与ocrTextPresent()完全相同，只不过它等待找到文本的反面情况。它可用于验证文本不存在。

OCR 将在组成桌面的所有可用屏幕上执行。至少在 Windows 和基于 X11 的系统上是如此。对于在 macOS 上实现多屏设置的 OCR，请联系技术支持。

可以通过传递通过可选 parameterMap 参数传入的条目来配置搜索行为。

• interval - OCR 搜索重试之间的最小毫秒数。默认值为 1000（1秒）。不同 OCR 尝试之间的实际间隔取决于 OCR 引擎的性能，可能会显著更长。
• timeout - 搜索指定文本并在报告找不到文本之前的时间（毫秒数）。默认值为 20000（20秒）。
• occurrence - 出现索引。默认情况下，将返回第一个文本匹配项（索引为1）。索引值2及以上将选择连续的匹配项，直到可用。
• language - OCR 引擎的语言提示。使用空字符串将使用 OCR 引擎的默认值。默认值是 testSettings.defaultOcrLanguage 属性的值。
• profiles - OCR 引擎特定配置文件名称的数组。此参数仅在支持配置文件的引擎中使用。
• options - 引擎特定选项名称和值的映射。这些选项在加载指定的配置文件后传递给 OCR 引擎。
• scaleFactor - 图像放大因子。在传递给 OCR 引擎之前，源图像通过该因子放大。默认值为 3.5。如果文本使用大字体渲染，可以将其设置为一个较低的值以提高 OCR 性能。
• message - 一个可选的详细描述（字符串类型），无论测试是否通过，都会添加到测试结果中，类似于Boolean test.compare(value1, value2)的message参数。

# Verify the 'Hier klicken' German text is displayed at least twice
test.ocrTextPresent("Hier klicken", {"occurrence": 2, "language": "German"})

// Verify the 'Hier klicken' German text is displayed at least twice
test.ocrTextPresent("Hier klicken", {occurrence: 2, language: "German"});

# Verify the 'Hier klicken' German text is displayed at least twice
test::ocrTextPresent("Hier klicken", {"occurrence" => 2, "language" => "German"});

# Verify the 'Hier klicken' German text is displayed at least twice
Test.ocrTextPresent("Hier klicken", {"occurrence" => 2, "language" => "German"})

# Verify the 'Hier klicken' German text is displayed at least twice
test ocrTextPresent "Hier klicken" {occurrence 2 language "German"}

默认情况下，此函数将反复捕获屏幕内容，直到找到指定的文本或经过20秒。通过parameterMap传入的timeout值可以设置更长的（或更短的）等待时间，单位为毫秒。

如果将搜索区域指定为最后一个参数，则仅在与之对应的区域内执行 OCR。搜索区域可以是 AUT 对象、一个 ScreenRectangle 对象或此类对象的数组。也可以是一个特殊的字符串值 "all"，在这种情况下，将使用所有顶层对象。

搜索区域也可以是图像对象对象。在这种情况下不会捕获新的截图，而是使用指定的图像。目前无法将 OCR 范围限制在图像对象的一个部分内；请使用Image.copy()来剪切相关部分。由于作为搜索区域的图像对象不可能随时间改变，此函数不会重复执行 OCR 并将立即返回结果。

# Verify the 'Click me' text is displayed on the MyWidget object
test.ocrTextPresent( "Click me", {}, waitForObject( names.MyWidget )

# Verify the 'Click me' text is displayed on multiple objects
test.ocrTextPresent( "Click me", {}, [ waitForObject( names.MyWidget ),
                                       waitForObject( names.MyOtherWidget ) ] )

# Verify the 'Click me' text is displayed on the left half of the MyWidget object
bounds = object.globalBounds( waitForObject( names.MyWidget ) )
bounds.width = bounds.width / 2
test.ocrTextPresent( "Click me", {}, bounds )

# Verify the 'Click me' text is displayed in the specified area
test.ocrTextPresent( "Click me", {}, UiTypes.ScreenRectangle( 100, 100, 200, 300 ) )

# Verify the 'Click me' text is displayed on all top-level objects
test.ocrTextPresent( "Click me", {}, "all" )

# Verify the 'Click me' text is displayed on the MyWidget object
test.ocrTextPresent( "Click me", {}, waitForObject( names.MyWidget ) );

// Verify the 'Click me' text is displayed on multiple objects
test.ocrTextPresent( "Click me", {}, [ waitForObject( names.MyWidget ),
                                       waitForObject( names.MyOtherWidget ) ] );

// Verify the 'Click me' text is displayed on the left half of the MyWidget object
var bounds = object.globalBounds( waitForObject( names.MyWidget ) );
bounds.width = bounds.width / 2
test.ocrTextPresent( "Click me", {}, bounds );

// Verify the 'Click me' text is displayed in the specified area
test.ocrTextPresent( "Click me", {}, new UiTypes.ScreenRectangle( 100, 100, 200, 300 ) );

// Verify the 'Click me' text is displayed on all top-level objects
test.ocrTextPresent( "Click me", {}, "all" );

# Verify the 'Click me' text is displayed on the MyWidget object
test::ocrTextPresent( "Click me", {}, waitForObject( names::MyWidget ) );

# Verify the 'Click me' text is displayed on multiple objects
test::ocrTextPresent( "Click me", {}, ( waitForObject( names::MyWidget ),
                                              waitForObject( names::MyOtherWidget ) ) );

# Verify the 'Click me' text is displayed on the left half of the MyWidget object
my $bounds = object::globalBounds( waitForObject( names::MyWidget ) );
$bounds->width = $bounds->width / 2;
test::ocrTextPresent( "Click me", {}, bounds );

# Verify the 'Click me' text is displayed in the specified area
test::ocrTextPresent( "Click me", {}, new UiTypes::ScreenRectangle( 100, 100, 200, 300 ) );

# Verify the 'Click me' text is displayed on all top-level objects
test::ocrTextPresent( "Click me", {}, "all" );

# Verify the 'Click me' text is displayed on the MyWidget object
Test.ocrTextPresent( "Click me", {}, waitForObject( names.MyWidget ) );

# Verify the 'Click me' text is displayed on multiple objects
Test.ocrTextPresent( "Click me", {}, [ waitForObject( names.MyWidget ),
                                       waitForObject( names.MyOtherWidget ) ] );

# Verify the 'Click me' text is displayed on the left half of the MyWidget object
bounds = Squish::Object.globalBounds( waitForObject( names.MyWidget ) );
bounds.width = bounds.width / 2
Test.ocrTextPresent( "Click me", {}, bounds );

# Verify the 'Click me' text is displayed in the specified area
Test.ocrTextPresent( "Click me", {}, UiTypes::ScreenRectangle.new( 100, 100, 200, 300 ) );

# Verify the 'Click me' text is displayed on all top-level objects
Test.ocrTextPresent( "Click me", {}, "all" );

# Verify the 'Click me' text is displayed on the MyWidget object
test ocrTextPresent "Click me" {} [ waitForObject $names::MyWidget ]

# Verify the 'Click me' text is displayed on multiple objects
test ocrTextPresent "Click me" {} { [ waitForObject $names::MyWidget ],
                                    [ waitForObject $names::MyOtherWidget ] }

# Verify the 'Click me' text is displayed on the left half of the MyWidget object
set bounds [object globalBounds [ waitForObject $names::MyWidget ] ]
property set $bounds width [ expr [ property get $bounds width ] / 2 ]
test ocrTextPresent "Click me" {} $bounds

# Verify the 'Click me' text is displayed in the specified area
test ocrTextPresent "Click me" {} [ construct ScreenRectangle 100 100 200 300 ]

# Verify the 'Click me' text is displayed on all top-level objects
test ocrTextPresent "Click me" {} "all"

确保函数始终成双成对调用

一些函数需要成对调用才能正确工作。例如，fixateResultContext & restoreResultContext应该一起使用，就像startsection & endSection一样。为了确保在脚本异常抛出时（或通过其他方式绕过其中一个语句的控制流，例如return;语句）也能保持这种情况，建议将函数对调用包装到辅助函数中，确保它们始终一起使用。

以下是确保fixateResultContext和restoreResultContext始终一起使用的一些示例。同样的方法也适用于startSection & endSection

#
# Python 2.5 or newer
#
def resultsReportedAtCallsite(ancestorLevel = 1):
    class Ctx:
        def __enter__(self):
            test.fixateResultContext(ancestorLevel + 1)
        def __exit__(self, exc_type, exc_value, traceback):
            test.restoreResultContext()
    return Ctx()

def libraryFunction():
    with resultsReportedAtCallsite():
        test.compare("Apples", "Oranges")

#
# Python 2.4 or earlier; these versions don't have the 'with' statement yet.
#
def withResultsReportedAtCallsite(callable, ancestorLevel = 1):
    test.fixateResultContext(ancestorLevel + 1)
    try:
        return callable()
    finally:
        test.restoreResultContext()

def libraryFunction():
    def go():
        test.compare("Apples", "Oranges")
    withResultsReportedAtCallsite(go)

function withResultsReportedAtCallsite(f)
{
    test.fixateResultContext(2);
    try {
        return f();
    } finally {
        test.restoreResultContext();
    }
}

function libraryFunction()
{
    withResultsReportedAtCallsite(function() {
        test.compare("Apples", "Oranges");
    });
}

sub withResultsReportedAtCallsite {
    my $code = shift;
    test::fixateResultContext(2);
    $code->();
    test::restoreResultContext();
}

sub libraryFunction
{
    withResultsReportedAtCallsite sub {
        test::compare("Apples", "Oranges");
    };
}

require 'squish'

include Squish

def withResultsReportedAtCallsite
  Test.fixateResultContext( 2 )
  begin
    yield
  ensure
    Test.restoreResultContext()
  end
end

def libraryFunction
  withResultsReportedAtCallsite do
    Test.compare("Apples", "Oranges")
  end
end

proc withResultsReportedAtCallsite {body} {
    test fixateResultContext 2
    uplevel 1 $body
    test restoreResultContext
}

proc libraryFunction {} {
    withResultsReportedAtCallsite {
        test compare "Apples" "Oranges"
    }
}

将测试结果分组

test.startSection(标题)

test.startSection(标题, 描述)

test.endSection()

这些函数可用于将测试结果分组为逻辑单元。一组比较或日志/警告语句可以包含在startSection/endSection中，以便将其作为单独的结果部分记录。当使用squishide显示结果部分时，它将结果部分以嵌套的测试结果集合的形式展示。在命令行上执行测试时，除非使用XML3报告生成器，否则每当一个部分开始或结束时，都会将日志消息添加到测试报告中。

比较文件

布尔型 test.compareTextFiles(预期文件路径, 实际文件路径)

布尔型 test.compareTextFiles(预期文件路径, 实际文件路径, 选项)

此函数将根据预期文件路径指定的预期文件与根据实际文件路径指定的实际文件进行比较。如果它们相等，则将类型为PASS的测试结果添加到测试日志，并返回一个true值。否则，将类型为FAIL的测试结果添加到测试日志，并返回一个false值。如果文件不同，将创建一个diff，其中显示了哪些行已更改，并在测试结果消息的详细信息中可以找到。

选项参数可以指定为映射或字典。到目前为止，可以设置以下选项

• strictLineEndings：如果将其设置为true，该函数将检测两个文件是否使用不同的换行符（例如，在Windows上的CR+LF或Unix上的LF）。默认设置为false。

//example 1: no options
test.compareTextFiles("expected.txt", "actual.txt");

//example 2: with options
test.compareTextFiles("expected.txt", "actual.txt", {'strictLineEndings': true});

#example 1: no options
test::compareTextFiles("expected.txt", "actual.txt");

#example 2: with options
test::compareTextFiles("expected.txt", "actual.txt", {"strictLineEndings" => 1});

#example 1: no options
test.compareTextFiles("expected.txt", "actual.txt")

#example 2: with options
test.compareTextFiles("expected.txt", "actual.txt", {'strictLineEndings': True})

#example 1: no options
Test.compareTextFiles("expected.txt", "actual.txt")

#example 2: with options
Test.compareTextFiles("expected.txt", "actual.txt", {'strictLineEndings' => True})

#example 1: no options
test compareTextFiles "expected.txt" "actual.txt"

#example 2: with options
test compareTextFiles "expected.txt" "actual.txt" [dict create strictLineEndings 1]

布尔型 test.compareXMLFiles(预期文件路径, 实际文件路径)

布尔型 test.compareXMLFiles(预期文件路径, 实际文件路径, 选项)

此函数将根据预期文件路径指定的预期XML文件与根据实际文件路径指定的实际XML文件进行比较。如果它们相等，则将类型为PASS的测试结果添加到测试日志，并返回一个true值。否则，将类型为FAIL的测试结果添加到测试日志，并返回一个false值。如果文件不同，结果消息详细信息将显示比较失败的行号和原因。

选项参数可以指定为映射或字典。到目前为止，可以设置以下选项

• ignoreNodeOrder：如果将其设置为true，该函数将忽略同一级别上的元素顺序，即具有相同父元素的元素。默认设置为false。
• ignoreAttributeOrder：如果将其设置为true，该函数将忽略元素内的属性顺序。默认设置为true。
• ignoreComments：如果将其设置为true，该函数将忽略所有注释。如果设置为false，则比较所有注释。默认设置为true。
• 文本中的空白处理：此选项可用于控制文本元素内部空白的处理方式。可以设置为 保留、规范化 或 修剪。如果设置为 保留，则保留所有空白字符；如果设置为 规范化，则将所有空白字符规范化为空格；如果设置为 修剪，则移除文本元素开头和结尾的空白字符。默认设置为 规范化。
• 属性值中的空白处理：此选项可用于控制属性值内部空白的处理方式。可以设置为 保留、规范化 或 修剪。如果设置为 保留，则保留所有空白字符；如果设置为 规范化，则将所有空白字符规范化为空格；如果设置为 修剪，则移除属性值开头和结尾的空白字符。默认设置为 保留。
• 忽略CDATA：如果设置为 true，则仅比较 CDATA 标签内的文本。标签本身将被忽略。如果设置为 false，则也会比较标签。默认设置为 true。
• 比较特殊标签：如果设置为 true，则声明、处理指令和 DOCTYPE 标签的值也将进行比较。默认设置为 false。
• 过滤元素：此选项接受代表标签名的字符串列表/数组。如果标签名包含在过滤元素列表中，则在比较两个文档时将忽略该标签。
• 过滤属性：此选项接受代表属性名的字符串列表/数组。如果属性名包含在过滤属性列表中，则在比较两个文档时将忽略该属性。

您还可以使用 Boolean test.compareTextFiles(expectedFilePath, actualFilePath) 函数比较 XML 文件，但此函数的优点是不考虑文件格式。相反，它直接查看文件结构，并比较节点和属性。

//example 1: no options
test.compareXMLFiles("expected.xml", "actual.xml");

//example 2: you only need to specify the options you need
test.compareXMLFiles("expected.xml", "actual.xml", {'ignoreNodeOrder': false});

//example 3: with filtered attributes and elements
filteredAttributes = ["version", "xmlns"];
filteredElements = ["uri"];
options = {'ignoreNodeOrder': false,
           'ignoreAttributeOrder': true,
           'filteredAttributes': filteredAttributes,
           'filteredElements': filteredElements,
           'whitespaceInTextHandling':'trim'};
test.compareXMLFiles("expected.xml", "actual.xml", options);

#example 1: no options
test::compareXMLFiles("expected.xml", "actual.xml");

#example 2: you only need to specify the options you need
test::compareXMLFiles("expected.xml", "actual.xml", {"ignoreNodeOrder" => 0});

#example 3: with filtered attributes and elements
my $filteredAttributes = ["version", "xmlns"];
my $filteredElements = ["uri"];
my $options = {"ignoreNodeOrder" => 0,
               "ignoreAttributeOrder" => 1,
               "filteredAttributes" => $filteredAttributes,
               "filteredElements" => $filteredElements,
               "whitespaceInTextHandling" => "trim"};
test::compareXMLFiles("expected.xml", "actual.xml", $options);

#example 1: no options
test.compareXMLFiles("expected.xml", "actual.xml")

#example 2: you only need to specify the options you need
test.compareXMLFiles("expected.xml", "actual.xml", {'ignoreNodeOrder': False})

#example 3: with filtered attributes and elements
filteredAttributes = ["version", "xmlns"]
filteredElements = ["uri"]
options = {'ignoreNodeOrder': False,
           'ignoreAttributeOrder': True,
           'filteredAttributes': filteredAttributes,
           'filteredElements': filteredElements,
           'whitespaceInTextHandling':'trim'}
test.compareXMLFiles("expected.xml", "actual.xml", options)

#example 1: no options
Test.compareXMLFiles("expected.xml", "actual.xml")

#example 2: you only need to specify the options you need
Test.compareXMLFiles("expected.xml", "actual.xml", {'ignoreNodeOrder' => false})

#example 3: with filtered attributes and elements
filteredAttributes = ["version", "xmlns"]
filteredElements = ["uri"]
options = {'ignoreNodeOrder' => false,
           'ignoreAttributeOrder' => true,
           'filteredAttributes' => filteredAttributes,
           'filteredElements' => filteredElements,
           'whitespaceInTextHandling' => 'trim'}
Test.compareXMLFiles("expected.xml", "actual.xml", options)

#example 1: no options
test compareXMLFiles "expected.xml" "actual.xml"

#example 2: you only need to specify the options you need
test compareXMLFiles "expected.xml" "actual.xml" [dict create ignoreNodeOrder 0]

#example 3: with filtered attributes and elements
set filteredAttributes [list version xmlns]
set filteredElements [list uri]
set options [dict create ignoreNodeOrder 0 \
                         ignoreAttributeOrder 1 \
                         filteredAttributes $filteredAttributes \
                         filteredElements $filteredElements \
                         whitespaceInTextHandling trim]
test compareXMLFiles "expected.xml" "actual.xml" $options

Boolean test.compareJSONFiles(expectedFilePath, actualFilePath)

此函数将指定的 expectedFilePath 的预期 JSON 文件与指定的 actualFilePath 的实际 JSON 文件进行比较。如果它们相等，则将添加测试结果类型为 PASS 的记录到测试日志，并返回该函数 true 值。否则，将添加类型为 FAIL 的测试结果记录到测试日志，并返回 false 值。如果文件不同，结果消息将显示比较失败的原因以及文本差异。

基于脚本的视觉验证点创建

createVisualVP(objectNameOrReference, vpFile)

此函数创建一个名为 vpFile 的 视觉验证点，可在之后的测试运行中使用 Boolean test.vp(name) 和 Boolean test.xvp(name)。而此操作通常通过 squishide 的点与点击来完成。

通过内部调用 saveObjectSnapshot(objectNameOrReference, snapshotImageFile.xml) 确定期望的视觉状态，其中 objectNameOrReference 表示对象。

新创建的验证点将启用所有内容、几何和截图检查。稍后可以使用视觉验证点编辑器修改这些检查。

如果vpFile已经存在，函数将抛出一个可捕获的脚本异常。

测试数据函数

Squish可以处理表格数据（行和列——或者在数据库术语中，记录和字段）。就Squish的数据处理函数而言，我们将“行”和“记录”视为同义词，同样，“列”和“字段”也是如此。

Squish可以从.tsv（制表符分隔值格式）、.csv（逗号分隔值格式）、.xls或.xlsx（Microsoft Excel工作表格式）文件中读取测试数据。在.csv和.tsv文件的情况下，Squish假设它们使用Unicode UTF-8编码——与所有测试脚本相同的编码。

测试数据函数用于数据驱动和关键字驱动测试。有关数据驱动测试的示例，请参阅教程；有关关键字驱动测试的示例，请参阅如何进行关键字驱动测试。

String testData.create(where, filename)

此函数返回可以写入的文件名。如果where参数为"shared"，则文件名将包含位于测试套件的共享测试数据目录（test_suite/shared/testdata/filename）的路径，如果where是"local"，则文件名将包含位于测试套件、测试用例的测试数据目录（test_suite/tst_case/testdata/filename）的路径。

此函数旨在在以“学习”模式运行脚本时使用，并希望动态创建测试数据。

Dataset testData.dataset(filename)

（以及testData.fieldNames、testData.field和testData.datasetExcel函数）用于数据驱动和关键字驱动测试。

testData.dataset函数返回一个数据集对象，该对象引用一个记录数组或元组。数据从由filename指定的文件中检索——如果数据格式是Squish可以识别的格式。

通常，不包含路径的filename会被给出（例如，mydata.csv）。在这种情况下，Squish首先尝试在测试用例的数据中查找文件（例如，如果测试用例有一个testdata文件夹，则在测试用例的testdata文件夹中）。如果失败，Squish接下来尝试在测试套件的共享数据文件夹中查找（例如，在测试套件的shared/testdata文件夹中）。如果找不到文件（或者找到但无法读取或理解），Squish会抛出一个可捕获的异常。如果指定了具有路径的filename（例如，C:\mydata\mydata.csv），则Squish会尝试读取该特定文件，如果文件不存在或不在Squish可以理解的格式中，则会抛出一个可捕获的异常。

可以使用下面的函数检索字段名称和字段值。

Dataset testData.datasetExcel(filename, sheetname)

该函数（以及 testData.fieldNames，testData.field 和 testData.dataset 函数）用于数据驱动和关键字驱动测试。

testData.datasetExcel 函数返回一个数据集对象，该对象指向一个记录数组或元组。数据从由 filename 和 sheetname 指定的文件中检索。当数据位于 Excel 格式中（即具有 .xls 或 .xlsx 扩展名）时，这是可能的。此函数是 testData.dataset 函数的一个规范。

有关函数行为的详细说明，请参阅上面的 testData.dataset 信息。唯一具体的是函数的第二个参数，即 sheetname。这是 Excel 文档中特定工作表的名字。此参数是可选的。默认情况下，将使用第一个工作表。

布尔值 testData.exists(filename)

这是一个旧的 API，通常最好使用 布尔值 RemoteSystem.exists(path) 替代。

如果名为 filename 的文件存在于 AUT 的当前工作目录中，则此函数返回一个真值；否则返回一个假值。

字符串 testData.field(record, fieldName)

字符串 testData.field(record, fieldIndex)

该函数返回由给定的字符串 fieldName 或给定的 fieldIndex 整数指定的字段的值，该值是从指定的 record（即从由 testData.dataset 函数返回的 数据集 中的特定行）中获得的。

有关用法示例，请参阅 如何进行数据驱动测试。

字符串序列 testData.fieldNames(record)

此函数返回特定 record（即从 testData.dataset 函数返回的 数据集 中的特定行）的字段名称数组或元组。

testData.get(filename)

此函数将名为 filename 的文件从 AUT 的当前工作目录复制到 squishrunner 的当前工作目录。通常，对于将远程文件复制到本地机器，最好使用 布尔值 RemoteSystem.download(remotePath, localPath) 替代。

testData.remove(filename)

此函数从 AUT 的当前工作目录中删除名为 filename 的文件。

testData.put(filename)

如果没有指定路径，则该函数将测试数据文件 filename 从测试用例目录复制到 AUT 的当前工作目录。如果指定了路径，则该函数将指定的文件复制到 AUT 的当前工作目录。当 AUT 终止时，复制的测试数据文件将自动删除。

该函数返回复制的文件的完整路径，或者在发生错误时抛出可以由测试脚本捕获的异常。

请注意，如果涉及多个 AUT（例如，如果一个 AUT 启动另一个程序），则在由在调用 testData.put 函数时的程序终止时发生删除。

对象映射函数

有关使用 squishide 操作对象映射的信息，请参阅对象映射视图。有关使用中的对象映射更多信息，请参阅对象映射。

objectMap.add(object)

此函数将给定的 object 添加到对象映射中。（可以使用 Object waitForObject(objectOrName) 函数或 Object findObject(objectName) 函数获取一个合适的对象。）

objectMap.load(filename)

此函数从给定的 filename 加载对象映射，并使用它来 替换 当前对象映射。如果文件不存在，将抛出异常并保持当前对象映射不变。

String objectMap.realName(object)

String objectMap.realName(symbolicName)

此函数返回给定 object 或具有给定 symbolicName 的对象的实际（多属性）名称。

String objectMap.symbolicName(object)

String objectMap.symbolicName(objectOrRealName)

此函数尝试返回对象映射中指定对象或真实名称的符号名称。

如果 objectOrRealName 是真实名称，并且不匹配任何现有对象，它将被简单地返回；不会抛出错误。

如果 objectOrRealName 是无效的真实名称，它将被简单地返回；不会抛出错误。

如果 objectOrRealName 是对对象的引用，并且对象映射不包含匹配此对象的对象名称，则将返回该对象的实际名称。

SequenceOfStrings objectMap.symbolicNames()

此函数返回一个包含所有映射符号名称的数组（Python 中的元组）。返回的名称是任意顺序的。

应用程序上下文

由 Squish 启动的每个 AUT 都有一个对应的 ApplicationContext 对象。这些对象提供以下属性和函数。（有关使用示例，请参阅如何使用 ApplicationContext 对象。）

以下是到与应用程序上下文相关函数、方法和属性的相关快速链接

ApplicationContext applicationContext(name)

此函数返回匹配给定 name 的 ApplicationContext 对象或不存在此类上下文的有效 ApplicationContext 对象。

String applicationContext.commandLine

此只读属性包含启动应用程序时使用的命令行。

String applicationContext.cwd

此只读属性包含应用程序的当前工作目录。

String applicationContext.environmentVariable(name)

此函数返回名为 name 的 AUT 进程环境变量的值或不存在此类环境变量时的空字符串。

String applicationContext.host

每个应用程序上下文都与一个 squishserver 进程相连。此只读属性包含 squishserver 进程运行的计算机/主机名或 TCP/IP 地址，以及连接到该应用程序上下文的计算机。

如果此应用程序上下文是由 ApplicationContext startApplication(autName) 创建的，则此属性也代表 AUT 运行的计算机/主机名或 TCP/IP 地址。

bool applicationContext.isFrozen(timeout)

如果应用程序在超时（以秒计）到期之前响应，则此函数返回 false 值；否则它返回 true 值。

bool applicationContext.isRunning

此只读属性为 true 如果 squishserver 和 AUT 中的 Squish Hook 之间的通信仍然活动，否则为 false。

当 Squish Hook 关闭时，squishserver 和 Squish Hook 之间的通信正在关闭。反过来，当 AUT 关闭时，Squish Hook 正在关闭。（例如，在 Qt 情况下，当主要 Qt 事件循环退出时。）

然而，AUT 的关闭可能不是立即的：AUT 可以在最终退出前的短时间内执行长时间操作，因此即使 AUT 进程仍然存在，一段时间内 isRunning 也可能为 false。

applicationContext.detach()

此函数从之前启动（或附加）的应用程序断开连接。

如果相应应用程序已通过 ApplicationContext startApplication(autName) 启动，Squish 将尝试关闭它，并最终（如果仍然运行）强制关闭它。

如果通过 ApplicationContext attachToApplication(autName) 将相应应用程序附加到，则 Squish 将使其运行但断开连接，从而留下应用程序在运行。然后可以使用 ApplicationContext attachToApplication(autName) 再次将其附加。

从应用程序脱钩后，不应再访问其任何对象。（这通常是通过使用在脱钩之前检索的引用对象来完成的。）

如果 applicationContext.detach() 的应用程序上下文是当前应用程序上下文，则当前应用程序上下文将更改为另一个（随机）应用程序上下文。所以，在继续之前，必须确保要操作的应用程序上下文是当前的一个。（见 SequenceOfApplicationContexts applicationContextList()，ApplicationContext currentApplicationContext() 和 setApplicationContext(contextHandle)。）

String applicationContext.name

这个只读属性表示应用程序的名称。在绝大多数平台和GUI工具包中，这是应用程序的进程名称。

int applicationContext.pid

这个只读属性表示应用程序的进程标识符。

int applicationContext.port

每个应用程序上下文都连接到一个 squishserver 进程。这个只读属性表示连接到应用程序上下文的 squishserver 进程的 TCP 端口号。

String applicationContext.readStderr()

此函数读取并返回自上次调用 readStderr 或自应用程序启动以来应用程序写入 stderr 流的所有内容。

String applicationContext.readStdout()

此函数读取并返回自上次调用 readStdout 或自应用程序启动以来应用程序写入 stdout 流的所有内容。

time applicationContext.startTime

这个只读属性表示应用程序启动时的时间。（属性的数据类型取决于所使用的脚本语言。）

int applicationContext.totalTime

这个只读属性表示 AUT 进程在用户和内核模式下被调度的总时间，用毫秒表示。

int applicationContext.usedMemory

这个只读属性表示 AUT 进程使用的内存量。对于 Windows 操作系统，值对应于工作集大小（以字节为单位）。对于 Linux 操作系统，值对应于常驻集合大小（RSS），以字节为单位。对于 macOS，它也是 RSS，但以千字节为单位。

SequenceOfApplicationContexts applicationContextList()

此函数返回一个数组（Python 中的元组）所有现有应用程序上下文的句柄。

ApplicationContext attachToApplication(autName)

ApplicationContext attachToApplication(autName, squishserver_host)

ApplicationContext attachToApplication(autName, squishserver_host, squishserver_port)

ApplicationContext attachToApplication(autName, squishserver_host, squishserver_port, timeoutSecs)

此函数使 Squish 连接到名为 autName 的应用程序，并返回其应用程序上下文的句柄。autName 必须是已与 squishserver 注册并可作为附加对象的 AUT 的应用程序名称。参见 配置 squishserver。由于应用程序应该已经运行，因此不能提供任何命令行选项。

squishserver_host 和 squishserver_port 指的是运行所需 squishserver 的计算机及其 TCP 端口。（这 不是 可附加 AUT 的主机和端口号。可附加 AUT 的主机和端口号在将可附加 AUT 注册到 squishserver 时指定（参见 注册可附加 AUT）。

在建立与可附加 AUT 的套接字连接后，使用参数 timeoutSecs。如果可附加 AUT 需要超过指定时间来响应附加尝试，则会抛出错误。如果没有指定 timeoutSecs，则使用 squishserver 的（最大启动时间）默认值——这是 20 秒，除非已更改；参见 Squish 服务器设置对话框。

如果您想指定超时，但不想更改主机或端口，可以通过将主机传递为空字符串（这将使 Squish 使用配置的主机—默认为 localhost），并通过将端口号传递为 -1 来做到这一点。

如果在附加过程中失败（例如，因为 AUT 没有运行），则此函数会抛出一个异常，该异常可以在测试脚本中捕获。如果没有捕获到异常，则在测试脚本执行过程中记录一个错误。

有关更多信息，请参见 附加到正在运行的应用程序。

ApplicationContext currentApplicationContext()

此函数返回当前应用程序上下文的句柄。

ApplicationContext defaultApplicationContext()

此函数返回默认应用程序上下文的句柄。最好使用 ApplicationContext currentApplicationContext() 函数。

setApplicationContext(contextHandle)

此函数可用于更改当前应用程序上下文。《contextHandle》对象是任何返回句柄的函数的句柄——SequenceOfApplicationContexts applicationContextList()、ApplicationContext attachToApplication(autName)、ApplicationContext defaultApplicationContext()、ApplicationContext currentApplicationContext() 和 ApplicationContext startApplication(autName)。如果省略参数，则激活默认上下文。

如果 contextHandle 对象无效——例如，如果它引用了一个已崩溃的应用程序——则会抛出一个可捕获的异常（Python 中的 TypeError）。

text getClipboardText()

设置剪贴板文本(setClipboardText(text))

这些函数可用于在AUT运行所在的机器上获取和设置剪贴板文本内容。

当处理包含换行符的剪贴板内容时，请注意它们的表示（\n 和 \r\n）是特定于操作系统的。

注意：对于非Qt X11应用程序，该功能确实需要安装xsel工具。对于使用替代窗口系统的非Qt应用程序，该功能还不可用。

ApplicationContext startApplication(autName)

ApplicationContext startApplication(autName, host)

ApplicationContext startApplication(autName, host, port)

ApplicationContext startApplication(autName, host, port, timeoutSecs)

此函数启动指定的应用程序并返回其应用程序上下文的句柄。autName 参数应该是已通过 squishserver 注册路径的应用程序名称。请参见 配置 squishserver。

也可以为 autName 使用可执行文件或 .jar 文件的绝对路径。此外，还可以在此处提供命令行选项。

可选地，作为第二个和第三个参数，可以指定 host 和 port。如果使用这些参数，则不是连接到默认主机和端口（如 squishide 的设置或 squishrunner 的命令行中指定的），而是连接到指定主机上监听指定端口的 squishserver。这使得能够从单个测试脚本中控制多台计算机上的多个应用程序。

第四个参数 timeoutSecs（秒的整数）也可以指定。这告诉 Squish 在抛出错误之前应该准备等待应用程序多长时间。如果没有指定，则使用 squishserver 的默认值——这是 20 秒，可以通过 服务器设置 > 应用程序行为 > 最大启动时间 来更改，或者通过执行 squishserver --config AUTTimeout numSeconds。

如果您想指定超时，但不想指定主机或端口，可以通过将主机作为空字符串传递（这将使 Squish 使用配置的主机——默认为 localhost），并通过将端口作为 -1 传递来实现。

有关如何使用应用程序上下文对象的信息，请参阅 如何使用 ApplicationContext 对象。（另请参阅 ApplicationContext waitForApplicationLaunch() 函数。）

String applicationContext.osName

此只读属性包含 AUT 运行的操作系统名称。可能包括以下名称：

• "Android" — Android
• "Darwin" — macOS 和 iOS
• "Linux" — Linux
• "QNX" — QNX
• "SunOS" — Solaris
• "Windows" — Windows

ApplicationContext connectTo(target)

ApplicationContext connectTo(target, host)

ApplicationContext connectTo(target, host, port)

该函数启动与远程桌面（例如，VNC）服务器的连接，并返回其应用程序上下文的句柄。其中target指定了连接参数。

连接目标可以是URL或参数映射。要连接到VNC服务器，URL和参数映射的参数都需要符合RFC 7869规范，该规范指定了以下字段

• scheme - 连接方案 "vnc";
• host - VNC服务器的主机名；
• port - VNC服务器的TCP端口。如果没有指定端口号，则使用默认值5900；
• VncUsername - 用于VNC认证的用户名。仅在服务器需要时使用；
• VncPassword - 用于VNC认证的密码。仅在服务器需要时使用。

Squish还提供了一种“本地”连接协议，允许squishserver直接连接到它正在运行的会话，而不需要任何额外的远程桌面服务器/认证。为了使用它，必须将"os"方案指定为目标参数的一部分。该"os"方案接受以下字段

• scheme - 连接方案 "os";
• display - 要连接的X11显示字符串。如果未指定，将使用默认显示字符串。此参数仅在类Unix系统中相关，在Windows和OSX系统中被忽略。

远程桌面连接始终通过squishserver实例路由。如果指定了host和port参数，Squish将使用位于指定地址的侦听服务器。默认情况下，将使用squishide设置中或squishrunner命令行上指定的服务器参数。

例如

connectTo("vnc://example.com")
connectTo("vnc://example.com:5901")
connectTo("vnc://example.com?VncPassword=secret")
connectTo("vnc://example.com:5901?VncUsername=user&VncPassword=secret")
connectTo("os://")

connectTo({"scheme": "vnc",
           "host": "example.com"})
connectTo({"scheme": "vnc",
           "host": "example.com",
           "port": 5901})
connectTo({"scheme": "vnc",
           "host": "example.com",
           "VncPassword": "secret"})
connectTo({"scheme": "vnc",
           "host": "example.com",
           "port": 5901,
           "VncUsername": "user",
           "VncPassword": "secret"})
connectTo({"scheme": "os"})

connectTo("vnc://example.com");
connectTo("vnc://example.com:5901");
connectTo("vnc://example.com?VncPassword=secret");
connectTo("vnc://example.com:5901?VncUsername=user&VncPassword=secret");
connectTo("os://");

connectTo({scheme: "vnc",
           host: "example.com"});
connectTo({scheme: "vnc",
           host: "example.com",
           port: 5901});
connectTo({scheme: "vnc",
           host: "example.com",
           VncPassword: "secret"});
connectTo({scheme: "vnc",
           host: "example.com",
           port: 5901,
           VncUsername: "user",
           VncPassword: "secret"});
connectTo({scheme: "os"});

connectTo("vnc://example.com");
connectTo("vnc://example.com:5901");
connectTo("vnc://example.com?VncPassword=secret");
connectTo("vnc://example.com:5901?VncUsername=user&VncPassword=secret");
connectTo("os://");

connectTo({"scheme" => "vnc",
           "host" => "example.com"});
connectTo({"scheme" => "vnc",
           "host" => "example.com",
           "port" => 5901});
connectTo({"scheme" => "vnc",
           "host" => "example.com",
           "VncPassword" => "secret"});
connectTo({"scheme" => "vnc",
           "host" => "example.com",
           "port" => 5901,
           "VncUsername" => "user",
           "VncPassword" => "secret"});
connectTo({"scheme" => "os"});

connectTo("vnc://example.com");
connectTo("vnc://example.com:5901");
connectTo("vnc://example.com?VncPassword=secret");
connectTo("vnc://example.com:5901?VncUsername=user&VncPassword=secret");
connectTo("os://");

connectTo({"scheme" => "vnc",
           "host" => "example.com"});
connectTo({"scheme" => "vnc",
           "host" => "example.com",
           "port" => 5901});
connectTo({"scheme" => "vnc",
           "host" => "example.com",
           "VncPassword" => "secret"});
connectTo({"scheme" => "vnc",
           "host" => "example.com",
           "port" => 5901,
           "VncUsername" => "user",
           "VncPassword" => "secret"});
connectTo({"scheme" => "os"});

connectTo "vnc://example.com"
connectTo "vnc://example.com:5901"
connectTo "vnc://example.com?VncPassword=secret"
connectTo "vnc://example.com:5901?VncUsername=user&VncPassword=secret"
connectTo "os://"

connectTo [ dict create "scheme" "vnc"
                        "host" "example.com" ]
connectTo [ dict create "scheme" "vnc"
                        "host" "example.com"
                        "port" 5901 ]
connectTo [ dict create "scheme" "vnc"
                        "host" "example.com"
                        "VncPassword" "secret" ]
connectTo [ dict create "scheme" "vnc"
                        "host" "example.com"
                        "port" 5901
                        "VncUsername" "user"
                        "VncPassword" "secret" ]
connectTo [ dict create "scheme" "os" ]

图像对象

全局Image对象提供了读取、保存和操作图像文件的功能。可以通过使用Image Image.load(fileName)从文件加载图像或使用任何Image object.grabScreenshot(object, [parameterMap])或grabDesktopScreenshot()测试API获取截图来获取Image类的实例。它可以作为图像搜索和OCR API的搜索区域参数，例如ScreenRectangle findImage(imageFile, [parameterMap], [searchRegion])、ScreenRectangle waitForImage(imageFile, [parameterMap], [searchRegion])、String getOcrText([parameterMap], [searchRegion])、ScreenRectangle findOcrText(text, [parameterMap], [searchRegion])、ScreenRectangle waitForOcrText(text, [parameterMap], [searchRegion])、SequenceOfObjects findAllOcrText(text, [parameterMap], [searchRegion])、Boolean test.imagePresent(imageFile, [parameterMap], [searchRegion])和Boolean test.ocrTextPresent(text, [parameterMap], [searchRegion])。

Image Image(QImage)

Image Image(QPixmap)

Image类型的构造函数。它使用AUT特定的QImage和QPixmap对象创建图像对象。

Image Image(width, height, [color])

《Image》类型的构造函数。它创建一个具有指定尺寸的图像。可以使用color参数指定图像像素的初始颜色。颜色可以指定为32位ARGB值，也可以指定为每个颜色通道的值集。

var img = new Image(100, 100, [255, 0, 0]);
img.save("C:\\red.png");

my $img = Image->new(100, 100, [255, 0, 0]);
$img->save("C:\\red.png");

img = Image(100, 100,[255, 0, 0])
img.save("C:\\red.png")

img = Image.new(100, 100, [255, 0, 0]);
img.save("C:\\red.png");

set img [image new 100 100 {255 0 0}]
invoke $img save "C:\\red.png"

Image Image.load(fileName)

这是一个静态的《Image》对象方法，默认情况下从测试用例目录下的指定文件中读取图像，并返回实例的引用。如果找不到文件或无法读取，则抛出异常。

参见findFile(where, filename)。

img = Image.load("indicator.png")
test.compare(img.width, 32)
test.compare(img.height, 32)

var img = Image.load("indicator.png");
test.compare(img.width, 32);
test.compare(img.height, 32);

my $img = Image->load("indicator.png");
test->compare($img->width, 32);
test->compare($img->height, 32);

img = Image::load("indicator.png");
Test::compare(img.width, 32)
Test::compare(img.height, 32)

set img [image load "indicator.png"]
test compare [property get $img width] 32
test compare [property get $img height] 32

在图像实例的原型中可以找到以下属性和函数。

Number width

此属性表示图像实例的宽度（以像素为单位）。此值是只读的。当尝试设置新值时将抛出异常。

Number height

此属性表示图像实例的高度（以像素为单位）。此值是只读的。当尝试设置新值时将抛出异常。

Image.copy///

Image.copy(x, y, width, height)

此函数返回图像一部分的副本。如果指定的几何形状不位于图像边界内（[(0, 0)...(width-1, height-1)]），则抛出异常。如果未指定坐标参数，则返回整个图像的副本。

Image.save(fileName)

此函数将图像实例保存到磁盘上的指定文件名。如果路径无效或不可写，则抛出异常。如果指定的路径是相对的，则文件相对于解释器的当前工作目录保存，默认情况下是当前正在执行的测试用例的位置。

保存文件的格式将基于文件扩展名。支持格式因平台/版本而异，但通常包括BMP、JPG、PNG、PPM、TIF、XBM和XPM。

var img = grabDesktopScreenshot();
img.save("C:\\screenshot1.png");

my $img = grabDesktopScreenshot();
$img->save("C:\\screenshot1.png");

img = grabDesktopScreenshot()
img.save("C:\\screenshot1.png")

img = grabDesktopScreenshot()
img.save("C:\\screenshot1.png")

set img [grabDesktopScreenshot]
invoke $img save "C:\\screenshot1.png"

Number Image.getPixelRGBA(x, y)

此函数返回一个数组，包含位于指定位置的像素的红色、绿色、蓝色和alpha颜色通道（按照该顺序）的颜色。如果像素不在图像边界内（从(0, 0)到(width-1, height-1)），则抛出异常。

pixel = img.getPixelRGBA(0, 0)
red = pixel[0];
green = pixel[1];
blue = pixel[2];
alpha = pixel[3];

var pixel = img.getPixelRGBA(0, 0);
var red = pixel[0];
var green = pixel[1];
var blue = pixel[2];
var alpha = pixel[3];

my @pixel = $img->getPixelRGBA(0, 0);
my red = $pixel[0];
my green = $pixel[1];
my blue = $pixel[2];
my alpha = $pixel[3];

pixel = img.getPixelRGBA(0, 0);
red = pixel[0];
green = pixel[1];
blue = pixel[2];
alpha = pixel[3];

set pix [invoke $img getPixelRGBA 0 0]
set red [lindex $pix 0]
set green [lindex $pix 1]
set blue [lindex $pix 2]
set alpha [lindex $pix 3]

完全不透明的像素的alpha值为255。完全透明的像素的alpha值为0。

Number Image.getPixel(x, y)

此函数返回指定位置的像素的32位ARGB颜色值。如果像素不在图像边界内（从(0, 0)到(width-1, height-1)），则抛出异常。此值可以直接与预期值（例如，纯绿色的0xff00ff00）进行比较。

pixel = img.getPixel(0, 0)
test.compare(pixel, 0xff102030)

var pixel = img.getPixel(0, 0);
test.compare(pixel, 0xff102030 );

my $pixel = $img->getPixel(0, 0);
test::compare($pixel, 0xff102030);

pixel = img.getPixel(0, 0);
Test::compare(pixel, 0xff102030);

set pixel [invoke $img getPixel 0 0]
test compare $pixel [expr 0xff102030]

Number Image.setPixel(x, y, rgbColor)

Number Image.setPixel(x, y, Array)

Number Image.setPixel(x, y, red, green, blue)

Number Image.setPixel(x, y, red, green, blue, alpha)

此函数更改指定位置的像素颜色。颜色可以指定为32位ARGB值，可以指定为每个颜色通道的值集合：红色、绿色、蓝色以及可选的alpha值，或这样的值数组；例如

img.setPixel(0, 0, 0xffff0000)
img.setPixel(0, 0, 255, 0, 0)
img.setPixel(0, 0, 255, 0, 0, 255)
img.setPixel(0, 0, [255, 0, 0])
img.setPixel(0, 0, [255, 0, 0, 255])

img.setPixel(0, 0, 0xffff0000);
img.setPixel(0, 0, 255, 0, 0);
img.setPixel(0, 0, 255, 0, 0, 255);
img.setPixel(0, 0, [255, 0, 0]);
img.setPixel(0, 0, [255, 0, 0, 255]);

$img->setPixel( 0, 0, 0xffff0000);
$img->setPixel( 0, 0, 255, 0, 0);
$img->setPixel( 0, 0, 255, 0, 0, 255 );
$img->setPixel( 0, 0, [255, 0, 0]);
$img->setPixel( 0, 0, [255, 0, 0, 255]);

img.setPixel(0, 0, 0xffff0000)
img.setPixel(0, 0, 255, 0, 0)
img.setPixel(0, 0, 255, 0, 0, 255)
img.setPixel(0, 0, [255, 0, 0])
img.setPixel(0, 0, [255, 0, 0, 255])

invoke $img setPixel 0 0 [expr 0xffff0000]
invoke $img setPixel 0 0 255 0 0
invoke $img setPixel 0 0 255 0 0 255
invoke $img setPixel 0 0 {255 0 0}
invoke $img setPixel 0 0 {255 0 0 255}

布尔图 Image.equals(otherImage)

此函数返回true，如果此图像等于其他图像。如果参数不引用图像实例，则抛出异常。

Screen 对象

有关屏幕的信息。要使用此 Screen 对象，必须在脚本文件中包含 Squish screen 库，并且 Squish 必须连接到/附加到 AUT。

source(findFile("scripts", "javascript/screen.js"));

function main()
{
    startApplication("myaut");

    // ...

    var scr = Screen.byIndex(0);
    var geom = scr.geometry;
    test.log("Screen is " + geom.width + " by " + geom.height);
}

use strict;
use utf8;
use warnings;

use Squish::Screen;

sub main {
    startApplication("myaut");

    # ...

    my $scr = Squish::Screen->byIndex(0);
    my $geom = $scr->geometry;
    test::log("Screen is " . $geom->width . " by " . $geom->height);
}

# -*- coding: utf-8 -*-
from screen import Screen

def main():
    startApplication("myaut")

    # ...

    scr = Screen.byIndex(0)
    geom = scr.geometry
    test.log("Screen is " + str(geom.width) + " by " + str(geom.height))

# encoding: UTF-8
require 'squish'
require 'squish/screen'

def main
    startApplication("myaut")

    # ...

    scr = Screen::byIndex(0)
    geom = scr.geometry
    Test.log("Screen is " + geom.width.to_s + " by " + geom.height.to_s)

package require squish::screen

    # ...

    set scr [Squish::Screen byIndex 0]
    set geom [$scr geometry]
    test log [concat "Screen is " [property get $geom width] " by " [property get $geom height]]

Screen.count()

此方法返回可用 Screen 对象的数量。

Screen.byIndex(index)

此方法返回一个 Screen 对象。指定的 index 必须在 0 到 Screen.count() - 1 范围内。

index

Screen 对象的只读属性，表示此 Screen 对象在所有可用 Screen 对象列表中的索引。

geometry

Screen 对象的只读属性，返回一个包含此 Screen 对象尺寸的 ScreenRectangle。

orientation

Screen 对象的可读/可写属性，通过以下四个属性之一指定此 Screen 的方向。除了以下属性外，还可用数字指定方向，1 表示 LandscapeOrientation，2 表示 PortraitOrientation，4 表示 ReverseLandscapeOrientation，8 表示 ReversePortraitOrientation。

Screen.LandscapeOrientation

Screen.PortraitOrientation

Screen.ReverseLandscapeOrientation

Screen.ReversePortraitOrientation

ToplevelWindow 对象

有关顶级窗口的信息和处理。要使用此 ToplevelWindow 对象，必须在脚本文件中包含 Squish toplevelwindow 库。

source(findFile("scripts", "javascript/toplevelwindow.js"));

    // ...

    var win = ToplevelWindow.focused();
    var geom = win.geometry;
    test.log("Focused window is " + geom.width + " by " + geom.height);

use strict;
use utf8;
use warnings;

use Squish::ToplevelWindow;

    # ...

    my $win = Squish::ToplevelWindow->focused();
    my $geom = $win->geometry;
    test::log("Focused window is " . $geom->width . " by " . $geom->height);

# -*- coding: utf-8 -*-
from toplevelwindow import *

    # ...

    win = ToplevelWindow.focused()
    geom = win.geometry
    test.log("Focused window is " + str(geom.width) + " by " + str(geom.height))

# encoding: UTF-8
require 'squish'
require 'squish/toplevelwindow'

    # ...

    win = ToplevelWindow::focused()
    geom = win.geometry
    test.log("Focused window is " + geom.width + " by " + geom.height)

package require squish::toplevelwindow

    # ...

    set win [Squish::ToplevelWindow focused]
    set geom [$win geometry]
    test log "Focused window is [property get $geom width] by [property get $geom height]"

ToplevelWindow.byName(objectname, timeout)

ToplevelWindow.byObject(object)

这些方法返回一个 ToplevelWindow 对象，给出给定的 objectname 或 object。第一个是一个方便方法，用于调用第二个，使用 Object waitForObject(objectOrName) 的结果。这些方法根据工具包接受不同的参数类型，并且应与大多数顶级窗口（如对话框、主窗口和浏览器标签页）一起工作。

tlw = ToplevelWindow.byName({'type': 'BrowserTab'})
#  ... is equivalent to ...
tlw = ToplevelWindow.byObject(activeBrowserTab())

ToplevelWindow.focused()

此方法返回一个具有键盘焦点的窗口的 ToplevelWindow 对象。如果没有找到具有键盘焦点的窗口，则引发异常。

geometry

ToplevelWindow 对象的只读属性，返回一个包含引用的窗口尺寸的 ScreenRectangle。

nativeObject

一个顶层数据窗口对象（ToplevelWindow）的只读属性，返回创建该顶层数据窗口对象的对象。

close()

此方法关闭由该顶层数据窗口对象引用的窗口。

maximize()

此方法将指定顶层数据窗口对象引用的窗口最大化。

minimize()

此方法最小化指定顶层数据窗口对象引用的窗口。

moveTo(x, y)

此方法将此顶层数据窗口对象引用的窗口客户端区域（不包括窗口边框）的左上角移动到指定的全局位置。

resizeTo(width, height)

此方法调整此顶层数据窗口对象引用的窗口客户端区域（不包括窗口边框）的大小，到指定的宽度和高度。

restore()

此方法将从全屏状态还原由指定的顶层数据窗口对象引用的窗口。

setFocus()

此方法将键盘输入焦点设置为指定的顶层数据窗口对象引用的窗口。

setForeground()

此方法将指定顶层数据窗口对象引用的窗口置于前台。

setFullscreen()

此方法将指定顶层数据窗口对象引用的窗口更改为全屏，即覆盖整个屏幕而不显示窗口边框。使用 restore() 取消此操作。

squishinfo 对象

全局的 squishinfo 对象提供了以下属性。

int squishinfo.major

此只读属性以单个整数形式存储Squish的主版本号（例如，4）。

int squishinfo.minor

此只读属性以单个整数形式存储Squish的次版本号（例如，0）。

int squishinfo.patch

此只读属性以单个整数形式存储Squish的修正版本号（例如，1）。

String squishinfo.resultDir

此只读属性存储结果目录的路径。

—squishinfo.settingsGroup

已废弃

—String

此只读属性持有当前测试活动设置组的名称。

String squishinfo.testCase

此只读属性包含了当前测试用例的路径。

字符串squishinfo.testCaseName

这个只读属性持有当前测试用例的名称。

字符串squishinfo.testSuiteName

这个只读属性持有当前测试套件的名称。

整数squishinfo.version

这个只读属性持有Squish的完整版本号（主要版本/次要版本/修补版本/发布版本）作为一个单一整数（进一步解释见下文）。

squishinfo.version的数字是一个唯一数字，代表Squish的完整版本号（主要版本/次要版本/修补版本/发布版本）。该数字由四个字节组成，通过将每一部分表示为一个单字节的十六进制数。所以Squish 4.0.1-final将表示为数字0x040001FF，其中0x04是主要版本（4），0x00是次要版本（0），0x01是修补版本（1），而0xFF是发布版本（final）。发布版本使用三个十六进制数之一进行编码：使用0xAA表示“alpha”，使用0xBB表示“beta”，使用0xFF表示“final”。

使用十六进制格式版本号可以轻松地在测试脚本中编写特定于版本的代码。以下是一个示例，其中我们只想在Squish 4.0.0-final或更高版本上执行某些代码（例如，利用某些Squish 4特定的功能）

if squishinfo.version >= 0x040000FF:
   # code meant for Squish version 4.0.0-final or higher

if (squishinfo.version >= 0x040000FF) {
   // code meant for Squish version 4.0.0-final or higher
}

if (squishinfo->version >= 0x040000FF) {
   # code meant for Squish version 4.0.0-final or higher
}

if Squishinfo.version >= 0x040000FF
   # code meant for Squish version 4.0.0-final or higher
end

if {[squishinfo version] >= 0x040000FF} {
   # code meant for Squish version 4.0.0-final or higher
}

字符串squishinfo.version_str

这个只读属性以人类可读的字符串形式（例如，“4.0.1-final”）持有Squish的版本号。

testInteraction函数

Squish为需要在回放期间与真实用户进行交互的测试提供了几个函数。这种交互包括手动验证中的简单问题以及提供用户输入，即手动驱动测试或在观察测试执行时做笔记。

testInteraction函数显示消息框，根据用户按下的按钮返回以下常量值之一

• testInteraction.Ok
• testInteraction.Yes
• testInteraction.No

任何显示对话框的testInteraction函数都会在其标题栏中显示当前测试脚本文件名和行号。

调用这些函数仅在以--interactive选项启动squishrunner时才有效（另请参阅squishrunner –testsuite: 以批量模式运行测试）。来自squishide的测试始终以交互模式运行。在非交互模式下调用任何testInteraction函数（除了testInteraction.isAvailable()）会导致脚本错误，从而终止脚本执行。

string testInteraction.choice(message, items)

显示一个对话框，其中message作为消息文本，以及一个可选择的items列表。返回的字符串包含所选项的文本或用户取消对话框时的空字符串。

var name = testInteraction.choice("Choose something", ["First", "Second", "Third"])
if (name == "") {
  test.warning("No item was chosen")
} else {
  test.log(item + " it is!")
}