JavaScript笔记和扩展API

Squish假设所有test.js文件都使用UTF-8编码。如果您预期在squishide之外编辑此类文件，请确保编辑器使用UTF-8加载和保存文件。

JavaScript语言文档

从理论上讲，任何JavaScript书籍或在线资源都适合学习该语言或查阅函数。不幸的是，大多数作者没有在JavaScript语言本身的功能和浏览器特定的扩展之间做出明确区分。在阅读此类文本时，请注意任何使用window或document对象的示例代码，因为这些是由浏览器提供的，而不是语言的一部分。

记住纯语言（即Squish支持的内容）与浏览器特定扩展之间的区别，您将能够从各种书籍和在线资源中找到所需的信息，同时避免混淆。以下是一些有用的在线JavaScript语言资源：

• Mozilla的核心JavaScript参考
• 在msdn.microsoft.com上的Microsoft的JScript语言参考
• 在www.devguru.com上的DevGuru JavaScript快速参考

如果您喜欢书籍，一本好的JavaScript书籍是David Flanagan所著的JavaScript: The Definitive Guide。

语言核心

Squish附带的JavaScript引擎基于ECMAScript语言规范（ECMA 262版3，以及后来版本的某些部分）。此标准中定义的语言核心包括运算符、控制结构、对象和其他在脚本语言中常用的功能。支持的内建类和成员的子集可以在Squish ECMAScript支持中找到。

纯JavaScript（即ECMAScript）语言没有内置的文件处理或网络支持，与Python和Tcl等其他脚本语言不同。这是因为JavaScript被设计成一个小型语言，可以安全地嵌入到应用程序中。然而，JavaScript也被设计成可以通过针对嵌入应用程序的特定自定义API进行扩展。在网页浏览器的情况下，有数百个函数和属性可以通过DOM API操作HTML文档，例如。在Squish的情况下，我们添加了大量的特定于测试的函数。我们还添加了一些下面描述的通用目的类。如果我们的添加功能不足以满足您的需求，请联系支持并请求增强。

Squish ECMAScript支持

本节是关于Squish支持的ECMAScript API子集。Squish还添加了非标准对象，如File、XML和SQL，以及特定的测试API，这些内容在其他部分的JavaScript笔记和扩展API中进行描述。

关键词

as、break、case、catch、const、continue、default、delete、do、else、export、extends、false、finally、for、from、function、if、in、instanceof、import、let、new、null、of、return、static、super、switch、this、throw、true、try、typeof、var、void、while、with

标点符号

{}, \c {}、(、)、[、]、.、,、; <、>、<=、>=、==、!=、===、!==、+、-、*、/、%、**、++、--、<<、>>、>>>、&、|、^、!、~、&&、||、??、... ?、:、=、+=、-=、*=、/=、%=、**=、<<=、>>=、>>>=、&=、|=、^=、&&=、||=、??= 和 =>。

全局对象

值属性

• NaN
• Infinity
• undefined

函数属性

• decodeURI()
• decodeURIComponent()
• encodeURI()
• encodeURIComponent()
• escape()
• eval()
• isFinite()
• parseFloat()
• parseInt()
• unescape()

构造函数属性

• Array
• Boolean
• Date
• Error
• Function
• Map
• Number
• Object
• RegExp
• Set
• String
• EvalError
• RangeError
• ReferenceError
• SyntaxError
• TypeError
• URIError

其他属性

• JSON
• Math

Array

原型函数属性

• concat()
• every()
• filter()
• forEach()
• indexOf()
• join()
• lastIndexOf()
• map()
• pop()
• push()
• reduce()
• reduceRight()
• reverse()
• shift()
• slice()
• some()
• sort()
• splice()
• toLocaleString()
• toString()
• unshift()

Boolean

原型函数属性

• toString()
• valueOf()

Date

原型函数属性

• getDate()
• getDay()
• getFullYear()
• getHours()
• getMilliseconds()
• getMinutes()
• getMonth()
• getSeconds()
• getTime()
• getTimezoneOffset()
• getUTCDate()
• getUTCDay()
• getUTCFullYear()
• getUTCHours()
• getUTCMilliseconds()
• getUTCMinutes()
• getUTCMonth()
• getUTCSeconds()
• getYear()
• setDate()
• setFullYear()
• setHours()
• setMilliseconds()
• setMinutes()
• setMonth()
• setSeconds()
• setTime()
• setUTCDate()
• setUTCFullYear()
• setUTCHours()
• setUTCMilliseconds()
• 设置UTC分钟数方法
• 设置UTC月份方法
• 设置UTC秒数方法
• 设置年份方法
• 转换为日期字符串方法
• 转换为GMT字符串方法
• 转换为ISO字符串方法
• 转换为JSON字符串方法
• 转换为本地日期字符串方法
• toLocaleString()
• 转换为本地时间字符串方法
• toString()
• 转换为时间字符串方法
• 转换为UTC字符串方法
• valueOf()

错误

原型值属性

• 消息
• 名称

函数属性

• toString()

函数

原型值属性

• 长度
• 名称

原型函数属性

• 应用方法
• 绑定方法
• 调用方法
• toString()

JSON对象

函数属性

• 解析方法
• 序列化方法

Map对象

原型函数属性

• 清除方法
• 删除方法
• forEach()
• 获取方法
• 存在方法
• 键方法
• 设置方法
• 值方法

Math对象

值属性

• E
• LN10
• LN2
• LOG10E
• LOG2E
• PI
• SQRT1_2
• SQRT2

函数属性

• 绝对值方法
• 反余弦函数方法
• 反正弦函数方法
• 反正切函数方法
• 反正切函数方法
• 向上取整方法
• 余弦函数方法
• 指数函数方法
• 向下取整方法
• 对数方法
• 最大值方法
• 最小值方法
• 幂函数方法
• 随机数方法
• 四舍五入方法
• 正弦函数方法
• 平方根方法
• 正切函数方法

数字

原型函数属性

• 转换为指数方法
• 转换为固定表示法方法
• toLocaleString()
• 转换为精度方法
• toString()
• valueOf()

对象

函数属性

• 创建方法
• 定义属性方法
• 定义属性方法
• 冻结方法
• 获取自有属性描述符方法
• 获取自有属性名称方法
• 获取原型方法
• 是方法
• 是否可扩展方法
• 是否冻结方法
• 是否密封方法
• 键方法
• 防止扩展方法
• 密封方法
• 设置原型方法

原型函数属性

• eval()
• 自有属性方法
• 是构造函数的原型方法
• 属性是否可枚举方法
• toLocaleString()
• toString()
• valueOf()
• 定义getter方法
• 定义setter方法

正则表达式

值属性

• $1...$9

原型值属性

• 全局方法
• 忽略大小写方法
• 最后索引方法
• 多行模式方法
• 源方法

Set对象

原型函数属性

• 添加方法
• 清除方法
• 删除方法
• 条目方法
• forEach()
• 存在方法
• 键方法
• 值方法

字符串

构造函数属性方法

• 从字符代码获取方法

原型函数属性

• 锚方法
• 大写方法
• 闪烁方法
• 加粗方法
• 获取字符方法
• 字符代码方法
• concat()
• 以...结束方法
• 固定方法
• 字体颜色方法
• 字体大小方法
• 包含方法
• indexOf()
• 斜体方法
• lastIndexOf()
• 链接方法
• 匹配方法
• 重复方法
• 替换方法
• 搜索方法
• slice()
• 缩小方法
• 分割方法
• 以...开始方法
• 删除线方法
• 下标方法
• 子字符串方法
• 子字符串方法
• 上标方法
• 转换为小写方法
• toString()
• 转换为大写方法
• 去除两端空格方法
• 去除左端空格方法
• 去除右端空格方法
• valueOf()

文件对象

File对象提供基本的文件处理功能，如检查文件是否存在、打开文件进行读或写、以及删除文件。在一般情况下，包含目录的路径可以使用/(在Windows上不需要转义)进行分隔。

示例

var file = File.open("C:\\testdata\\input.txt", "r");
file.encoding = "system"; // Should only be needed for some Windows AUTs
var text = file.read();
inputField.setText(text);

默认文件编码是"utf-8"，这是文本文件的最佳编码。

以下是一些指向File对象属性和方法快速链接。

file.close()

此方法关闭调用它的文件对象。一旦关闭，就无法对该文件对象进行读取或写入。

File.copy(source, target)

该函数将文件 source 复制到 target。如果复制失败，则会抛出异常。

如果 target 已经存在，则复制会失败。如果需要，可以使用 Boolean File.remove(fileName) 在复制前腾出空间。

String file.encoding

此属性定义了在读取或写入文件时使用的编码。默认编码是 "utf-8"。对于不支持 UTF-8 的 AUT（例如某些 Windows 应用程序），将编码设置为 "system" 可能有所帮助，因为这将使 Squish 使用当前系统区域设置。其他可能的值有 "ucs-2"（2 字节 Unicode，用于在 Windows 上读取 UTF-16）和 "latin1"（也称为 ISO 8859-1），它包含 US-ASCII 范围。

应在进行任何读取或写入之前设置此属性。

Boolean File.exists(fileOrDirectory)

如果指定的 fileOrDirectory 存在，此函数返回 true；否则返回 false。《code translate="no">fileOrDirectory 可以包含绝对路径、相对路径或无路径，此时使用当前工作目录。

文件 File.open(fileName)

文件 File.open(fileName, mode)

此函数尝试打开指定的 fileName（可能包含绝对路径、相对路径或无路径，此时使用当前工作目录）。可选的 mode 参数默认为 "r"（以读取方式打开）。如果指定了 mode，它必须是："a"（以追加方式打开）、或 "r"（以读取方式打开）、或 "w"（以写入方式打开）。如果无法打开 fileName，则会抛出可捕获的异常。

一旦文件成功打开，就可以调用其方法。对于以追加或写入方式打开的文件，可以调用 file.write(string) 方法，对于以读取方式打开的文件，可以调用 String file.read() 和 String file.readln() 方法。并且对于任何打开的文件，都可以调用 file.close() 方法。

StringList File.glob(pattern, [pattern...])

此函数返回匹配任何给定模式的路径列表。

String file.read()

此方法读取由 File File.open(fileName) 函数返回的文件对象的全部内容——如果文件是以读取模式打开的。假定文件内容是使用 UTF-8 编码的纯文本（除非更改了 file.encoding 属性）。

String file.readln()

此方法从由File File.open(fileName)函数返回的文件对象中读取下一行（前提是在读取模式中打开了文件）。假设文件内容使用UTF-8编码（除非file.encoding属性被更改）。返回的每一行都不包含换行符，如果尝试读取最后一行之后的文本，则返回null。

布尔值 File.remove(fileName)

该函数尝试移除指定的fileName（可能包含绝对路径、相对路径或无路径，在这种情况下使用当前工作目录）。如果文件成功移除，则函数返回true；否则返回false。

字符串 File.separator

全局File对象的只读separator属性包含操作系统使用的文件分隔符。例如，在Windows上，它包含"\"，而在类Unix系统上，包含"/"。

数字 File.size(fileName)

此函数返回指定fileName（可能包含绝对路径、相对路径或无路径，在这种情况下使用当前工作目录）的大小。

file.write(string)

此方法将给定的string写入由File File.open(fileName)函数返回的文件对象（前提是在追加或写入模式中打开了文件）。使用UTF-8编码写入string（除非file.encoding属性被更改）。

控制台对象

console对象提供用于与脚本执行进行基本交互的函数。console对象不是一个标准的JavaScript对象，但它在网络浏览器中广为人知。

以下是一些控制台对象的快速链接

console.assert(bool, string [可选])

如果第一个参数评估为false，则脚本执行将停止，并将错误消息写入测试结果，否则不会发生任何事情。第二个参数是可选的，允许将用户指定的消息写入测试结果。

下面是一个展示此函数用法的示例

var index = findIndexOfSomething( "something" );
Console.assert( index >= 0, "Something not found, execution aborted!" );
something[ index ].doSomething();

OS对象

OS对象提供与操作系统进行基本交互的函数。包括执行命令（即运行程序）、获取和设置当前目录以及获取和设置环境变量等功能。

以下是一些OS对象的属性和快速链接

数组 OS.argv

OS对象的只读argv属性包含当前测试脚本的绝对文件名，后面跟着传递给squishrunner的脚本参数列表（另请参阅squishrunner）。

以下是一个如何读取可选脚本参数的示例

var filename = "defaultfile.txt";
if (OS.argv.length > 1) {
    filename = OS.argv[1];
}

String OS.capture(command)

此函数在shell（控制台）中执行所给的command，就像int OS.system(command)函数一样。要执行的command字符串必须包含要执行的命令名称，并提供可选的命令行参数和shell重定向字符。此函数与int OS.system(command)函数的不同之处在于，它会捕获命令的输出，即通常到达控制台的任何文本（stdout流），并将其作为字符串返回。

以下是一个在Windows上执行命令并捕获其输出的示例

var files = OS.capture("dir C:\\temp\\*.dat").split('\n');
for (var i in files) {
    var file = files[i];
    // ...
}

请注意，在这种情况下，使用跨平台的Array OS.listDir(path)函数来获取目录中的文件列表更加容易、更好。

OS.chdir(path)

此函数将测试脚本的当前工作目录更改到指定的path。

示例

var path = OS.cwd() + "/results";
OS.chdir(path);

String OS.cwd()

此函数以字符串形式返回当前工作目录。

示例

var path = OS.cwd();
test.log("Current working directory: " + path);

String OS.getenv(name)

此函数返回给定name的环境变量值，如果不存在此类环境变量，则返回一个空字符串。（另见，OS.setenv(name, value)。）

示例

var homeDir = OS.getenv("HOME");
test.log("Current user's home directory: " + homeDir);

Array OS.listDir(path)

此函数返回指定path目录中的所有文件和目录列表，但不包括特殊的目录.（当前）和..（父），此函数不递归到子目录。

以下是一个记录在Windows输出目录中生成的所有文件的示例

var files = OS.listDir("C:\\temp\\output");
for (var i in files)
    test.log("Found generated file: " + files[i]);

String OS.machine

OS对象只读的machine属性包含squishrunner在运行的硬件名称。在Microsoft Windows系统上，值是“x86”、“amd64”、“arm64”或“ia64”。在类Unix系统上，值与uname -m的输出相同，例如“i686”、“x86_64”等。

String OS.name

OS对象只读的name属性包含squishrunner在运行的操作系统名称。在Microsoft Windows系统上，值是“Windows”。在类Unix系统上，值与uname -s的输出相同，例如“Linux”、“Solaris”、“Darwin”等。

OS.pause(msecs)

此函数使脚本暂停指定的毫秒数。与snooze(seconds)函数不同，延迟是固定的，且不受当前snooze因素设置的影响。

Boolean OS.removeRecursively(path)

此函数删除位于path处的目录及其全部内容。如果目录最初不存在，则函数返回true并成功执行。（所期望的结果仍然实现。）

示例

OS.system("mkdir exampleDir");
var file = File.open("exampleDir/data", "w");
file.write("some data");
file.close();
var result = OS.removeRecursively("exampleDir");
test.log("Deletion result: " + result);

Boolean OS.rmdir(path)

此函数删除路径 path 中找到的目录。删除时目录必须为空。成功时，函数返回 true。

示例

var oldDir = "C:\\build_old";
var result = OS.rmdir(oldDir);
test.log("Deletion result: " + result);

布尔值 OS.mkpath(path)

此函数在路径 path 处创建目录，如果路径是绝对路径，或者路径为 current_directory/path，如果路径是相对路径。重要提示：如果 path 中提到的所有必需目录尚不存在，将会创建它们。如果出现以下情况，函数将引发错误：

(a) 调用参数不正确；或者

(b) 目录已存在；或者

(c) 由于任何其他原因（如I/O错误）无法创建目录。

如果成功，则函数返回 true。

示例

var Dir = "C:\\some_new_directory";
var result = OS.mkpath(Dir);
test.log("Directory created: " + result);

OS.setenv(name, value)

此函数会将名为 name 的环境变量设置为给定 value。如果 name 环境变量尚不存在，它将被创建（并且设置为给定 value）。（有关详细信息，请参阅 String OS.getenv(name)。）

示例

var preferredEditor = "vim";
OS.setenv("EDITOR", preferredEditor);

int OS.system(command)

此函数在shell（控制台）中执行给定的 command。如果执行成功，则返回状态；否则返回-1，表示发生了错误。必须以要执行的命令的名称为字符串的 command，并且可选包括命令行参数和shell重定向字符。

以下是一个例子，它在Windows上执行自定义应用程序，并将其 stdout 流重定向到文件。

var result = OS.system("C:\\testprograms\\readresult.exe > output.txt");
if (result == -1)
    test.fatal("readresult error occurred");
else if (result != 0)
   test.warning("readresult failed");

以下是一个例子：此示例在Unix系统上发送邮件。

var msg = "This is a mail from Squish";
OS.system("echo '" + msg + "' | mail -s Subject [email protected]");

还可以参考 String OS.capture(command) 函数。

数组 OS.version

OS对象的只读属性 version 持有一个数组，其中包含squishrunner在运行的操作系统信息。数组的元素命名分别为"major"、"minor"和"name"，分别表示版本号和可读表示形式。

以下是一个使用此信息的例子，以确保在支持的操作系统上执行测试。

var major = OS.version.major;
if (major < 7)
    test.warning("Unsupported OS version " + OS.version.name);

XML对象

XML 对象提供了一个解析函数，它作用在带XML标记的文字字符串上，并返回一个 XMLNode 对象，该对象提供了允许遍历和查询XML的方法。

XMLNode XML.parse(markup)

此函数解析给定的XML标记字符串，并返回一个表示文档树根的文档节点对象。如果解析失败，则会抛出一个可捕获的异常。

请注意，即使指定了不是UTF-8的编码，假定XML使用UTF-8编码（这是没有指定编码的XML文件的默认编码）。

XMLNode xmlNode.firstChild

此只读节点属性持有此节点的前一个子节点——或者如果此节点没有子节点，则为空节点。

String xmlNode.getAttribute(attributeName)

此节点方法返回一个包含节点 attributeName 属性值的字符串。如果节点没有名为 attributeName 的属性，则方法的行为是未定义的。如果 attributeName 是空字符串，则会抛出一个可捕获的异常。可以使用 String xmlNode.getAttributeNames() 函数检索节点所有属性的名字。

String xmlNode.getAttributeNames()

此节点方法返回一个包含节点所有属性名的字符串列表。这些名字中的任何一个都可以作为 String xmlNode.getAttribute(attributeName) 函数的参数来获取相应属性值。

Boolean xmlNode.hasAttribute(attributeName)

如果节点有一个名为 attributeName 的属性，则该函数返回 true；否则返回 false。

ListOfXMLNode xmlNode.getElementsByTagName(tagName)

此函数返回给定 tagName 的 XMLNode 对象列表。

XMLNode XMLNode.selectSingleNode(XPathExpression)

此函数在一个 XMLNode 对象的父文档上评估给定的 XPath.Expression，并检索评估返回的第一个 XMLNode 对象，或者（如果给定的 XPath 表达式没有评估出任何内容）返回 null。

jsTupelOfValues xmlNode.selectNodes(XPath.Expression)

此函数在一个 XMLNode 对象的父文档上评估一个 XPath.Expression，然后返回一个包含 XMLNode 对象的列表。

jsValue XMLNode.getSingleValueByXPath(XPathExpression)

此函数在对一个 XMLNode 对象的父文档评估一个给定的 XPath.Expression，并检索评估返回的第一个 XMLNode 对象的内容。因此返回类型因返回的 XMLNode 对象包含的内容类型而异。如果评估不会返回任何节点，则返回 null。

jsTupelOfValues XMLNode.getValuesByXPath(XPath.Expression)

此函数在一个 XMLNode 对象的父文档上评估一个 XPath.Expression，并返回一个 JavaScript 元组，其元素可以是返回的 XMLNode 对象直接包含的内容，或者是如果在评估中可能返回包含更多 XMLNode 子对象的多级子树，则这些节点将按原样包含在元组中。

Boolean xmlNode.isNull

此只读节点属性当节点为空节点时为 true，否则为 false。

XMLNode xmlNode.nextSibling

此只读节点属性包含此节点的下一个兄弟节点（如果此节点没有下一个兄弟节点，则为空节点）。

字符串 xmlNode.nodeName

此节点属性包含节点名称，它是元素节点的标签名。对于文档节点，节点名称始终为 "<匿名xml文档>"。

整数 xmlNode.nodeType

此节点属性包含节点类型作为枚举值。可能的类型值有

• 0 : XML.DocumentNode
• 1 : XML.ElementNode
• 2 : XML.CommentNode
• 3 : XML.UnknownType
• 4 : XML.TextNode
• 5 : XML.DeclarationNode

字符串 xmlNode.nodeValue

此节点属性包含节点的值。其意义取决于节点的类型，如下所示

• XML.CommentNode 返回注释文本
• XML.DeclarationNode 提供空文本
• XML.DocumentNode 提供固定文本 "<匿名xml文档>"
• XML.TextNode 提供文本字符串
• XML.UnknownType 提供标签内容

XMLNode xmlNode.parentNode

此节点属性包含节点的父节点，如果此节点没有父节点，则为空节点。（例如，文档节点没有父节点。）

字符串 xmlNode.textContent

此节点属性包含此节点中的文本（可能为空字符串）。

请注意，此节点属性将不会遍历其子节点以生成所有文本的连接。例如

var documentNode = XML.parse("<a>Hello</a>");
var anchorNode = documentNode.firstChild;
test.verify(anchorNode.textContent == "Hello");

documentNode = XML.parse("<a><b>Hello</b></a>");
anchorNode = documentNode.firstChild;
test.verify(anchorNode.textContent == "");
var boldNode = anchorNode.firstChild;
test.verify(boldNode.textContent == "Hello");

字符串 xmlNode.toXMLString()

此函数返回一个 XMLNode 对象的XML格式字符串表示，包括标签、属性和子元素。

SQL

Squish 提供了访问SQL数据库的自己的API，因为JavaScript规范不包括它们。要查看SQL API的实际应用，请参阅如何从Squish测试脚本中访问数据库中的JavaScript示例。

SQL对象

SQL 对象提供了一种连接数据库、在数据库上执行查询以及遍历和检查结果的方法。此功能可能用于检索测试数据或为AUT提供数据。

SQLConnection SQL.connect(informationObject)

此函数尝试连接到SQL数据库。如果成功，则返回一个 SQLConnection 对象 - 可以在此数据库上执行SQL语句。如果连接失败，则抛出一个可捕获的异常。建立连接所需的信息必须作为对象传递，该对象的属性随后将进行解释。

以下是一个示例调用，展示如何连接到名为"dulsberg"的主机上的MySQL服务器，使用提供的用户名和密码

var conn = SQL.connect( { Driver: "MySQL",
                          Host: "dulsberg",
                          Port: 1342,
                          Database: "mydatabase",
                          UserName: "test",
                          Password: "secretPhrase" } );

对象的属性具有以下意义

• 驱动：驱动用于指定我们连接到哪种类型的数据库。可能的值是
  • DB2^*：IBM DB2，v7.1及以上版本
  • IBase^*：Borland Interbase驱动程序
  • MySQL：MySQL驱动程序
  • ODBC：ODBC驱动程序（包括Microsoft SQL Server）
  • Oracle^*：Oracle调用接口驱动
  • PostgreSQL：PostgreSQL v8.x 驱动
  • SQLite：SQLite 3 驱动
  • Sybase^*：Sybase 自适应服务器

  注意：带有星号(*)的驱动在Squish二进制软件包中不支持。这通常是因为数据库供应商的许可不允许在没有拥有其产品许可的情况下重新分发其客户端库。解决方案是尝试ODBC驱动，或者自己构建针对包含特定SQL数据库支持的Qt库的Squish。

• 主机：用于指定SQL数据库安装的计算机的名称（或IP地址）。
• 端口：用于指定应建立连接的远程计算机上的端口号。如果省略，使用指定驱动的默认端口。
• 数据库：用于指定要建立连接的数据库的名称。
• 数据源：用于指定要使用的数据源名称（DSN）。请注意，当使用ODBC驱动时，指定此属性是必要的。
• 用户名：用于指定登录数据库时使用的用户名。
• 密码：用于指定登录数据库时使用的密码。如果省略，则假定密码为空。

SQLConnection对象

SQLConnection对象由上述SQLConnection SQL.connect(informationObject)函数返回；该对象提供以下列出的方法。

sqlConnection.close()

此方法关闭SQL连接。

Number sqlConnection.execute(sql)

此方法在SQLConnection对象上执行给定的sql语句（例如DELETE、INSERT或UPDATE）。如果语句成功，则返回受影响的行数；如果无法确定该值，则返回-1。如果发生错误，将抛出一个可捕获的异常。

如果需要读取语句返回的结果（例如，对于CALL），请使用SQLResult sqlConnection.query(sql)。

SQLResult sqlConnection.query(sql)

此方法在SQLConnection对象上执行给定的sql语句（例如，一个SELECT语句）。如果语句成功，则返回一个SQLResult对象。如果发生错误，则抛出一个可捕获的异常。

以下是一个示例，展示了如何在连接对象上执行SQL查询。

var result = connection.query("SELECT last_name, first_name " +
        "FROM people WHERE country LIKE 'A%';");

SQLResult对象

SQLResult对象由Number sqlConnection.execute(sql)和SQLResult sqlConnection.query(sql)方法返回。一个SQLResult对象提供以下列出的函数和属性。请注意，在SELECT语句的情况下，如果检索到了某些行，SQLResult对象将自动设置为第一行。

Boolean sqlResult.isValid

如果SQLResult对象处于有效状态，则此属性为true；否则为false。一些函数返回无效结果对象以指示错误或其它特殊情况（见下文）。

int sqlResult.size

该属性保存由查询影响的行数（例如，删除、插入或更新的行数）——或者如果无法确定的数量为-1。对于SELECT查询，该属性用于保存该结果包含的行数。

sqlResult.toFirst()

此函数将导航到本结果的第一行。如果您想多次遍历行，这将很有用：在通过< MONTHLYkehResult.toNext()函数处理行之后，调用此函数将返回到第一行，从而可以再次使用< MONTHLYkehResult.toNext()函数。

sqlResult.toNext()

此函数将导航到此SQL结果中的下一行。如果没有下一行（因为没有行或因为我们已经导航到最后一行），此SQLResult对象将被标记为无效。这个函数和isValid属性使得遍历SELECT查询的结果变得容易。例如

var result = connection.query("SELECT last_name, first_name " +
        "FROM people WHERE country LIKE 'A%';");
// result is automatically set the first row
while (result.isValid) {
    // do something with the result
    result.toNext();
}

String sqlResult.value(fieldNumber|fieldName)

此函数可以用来获取当前行（记录）中指定列（字段）的数据。列可以通过其位置（从0开始计数）或使用（大小写不敏感）字段名来识别。给定列中的数据将被隐式转换为字符串。请注意，您也可以使用括号语法（如以下示例所示）作为快捷方式。

var result = connection.query("SELECT first_name, last_name " +
        "FROM people WHERE country LIKE 'A%';");
// result is automatically set the first row
while (result.isValid) {
    var name1 = result.value(0) + " " + result.value(1);
    var name2 = result.value("first_name") + " " + result.value("last_name");
    var name3 = result["first_name"] + " " + result["last_name"];
    test.verify(name1 == name2 && name2 == name3);
    result.toNext();
}

此示例显示了三种不同的方式来索引字段，它们是等效的。

套接字对象

Socket对象可以用作TCP客户端套接字，以连接到服务器套接字，并读取和写入字符串。

示例

var socket = Socket.connect("192.168.1.42", 4711);
socket.encoding = "latin1";
socket.writeString("hello");
var line = socket.readLine();
socket.close();

以下是一些指向Socket对象的属性和方法的快速链接。

socket.close()

该方法关闭套接字连接。一旦关闭，套接字对象就无法读取或写入。

socket Socket.connect(host, port)

此函数尝试连接到指定的主机名（或IP地址）和端口，并返回一个套接字对象。如果连接失败，则会抛出一个可捕获的异常。

String socket.encoding

socket对象的encoding属性保存用于读取和写入字符串的编码。默认编码是"utf-8"。其他可能值是"ucs-2"（2字节Unicode）和"latin1"（也称为ISO 8859-1），它包括US-ASCII范围。

从容行为之前应设置此属性。

String socket.localAddress

socket对象的localAddress属性保存套接字在本地机器上使用的地址。

Number socket.localPort

socket对象的localPort属性保存套接字在本地机器上使用的端口。

Number socket.readInt8()

此方法从套接字中读取一个有符号的8位整数。成功时返回整数值，否则抛出可捕获的异常。

Number socket.readInt32()

此方法从套接字中读取一个有符号的32位整数。成功时返回整数值，否则抛出可捕获的异常。

String socket.readLine()

此方法读取直到从由socket Socket.connect(host, port)函数返回的套接字中读取到"\n"或"\r\n"为止。假定内容使用UTF-8编码的文本（除非已更改socket.encoding属性）。成功时返回无行终止符的字符串。如果没有接收到行终止符，将抛出可捕获的异常。

String socket.remoteAddress

socket对象的remoteAddress属性保存远程机器上用于套接字的地址。

Number socket.remotePort

socket对象的remotePort属性保存远程机器上用于套接字的端口号。

Number socket.timeout

socket对象的timeout属性持有套接字的读写操作的超时时间。它是一个以秒为单位的整数，默认为20秒。

应在进行任何读取或写入之前设置此属性。

Socket.writeString(string)

此方法将给定的string写入由socket Socket.connect(host, port)函数返回的套接字对象。使用UTF-8编码写入字符串（除非已更改socket.encoding属性）。如果写入失败，将抛出可捕获的异常。

WebSocket 对象

WebSocket对象通过WebSocket协议实现与服务器基于文本的通信。其功能在测试脚本中使用时，直到完成才阻塞。

var socket;
try {
    socket = WebSocket.connect("websocket-server", 80);
} catch (e) {
    test.log("Could not connect: " + e);
    return;
}

socket.timeout = 500;
socket.sendTextMessage( "'Quack!' said the frog." );
test.log("received: " + socket.receiveTextMessage());
socket.close();

WebSocket WebSocket.connect( hostname)

连接到hostname:port并返回一个WebSocket对象（成功时）。失败时，将抛出异常。

websocket.close()

关闭WebSocket连接。

websocket.sendTextMessage( message)

通过WebSocket发送文本消息。失败时抛出异常。

String websocket.receiveTextMessage()

从WebSocket接收消息。如果没有接收内容，将抛出异常。

String websocket.host

这是一个只读属性，它保存了套接字连接到的主机。

Boolean websocket.open

这是一个只读属性，它告知该套接字目前是否打开。

Number websocket.port

这是一个只读属性，它保存了套接字连接到的端口号。

Number websocket.timeout

保存用于通过WebSocket发送和接收数据的超时时间（默认：3000毫秒）。此属性可随时更改，并期望一个毫秒值。

XMLHttpRequest对象

XMLHttpRequest对象可以用作HTTP客户端，可以发起GET、HEAD、POST、PUT、PATCH或DELETE请求。其用法从查询Web页面内容延伸到所谓的REST调用，其中数据以纯文本、XML或JSON形式传输。

XMLHttpRequest XMLHttpRequest()

XMLHttpRequest类型的构造函数。

XMLHttpRequest.abort()

此函数将重置客户端对象，并将readyState属性改回UNSENT。

String XMLHttpRequest.getResponseHeader(header)

此函数从与header字段名匹配的响应中返回header字段值。调用示例可能记录类似于"text/plain"的结果。

var client = new XMLHttpRequest();
client.open("GET", "http://www.example.com/result.txt", false);
client.send();
test.log(client.getResponseHeader("Content-Type"));

String XMLHttpRequest.getAllResponseHeaders()

此函数返回所有响应头。其中每个键值对都是由一个CR/LF序列分隔。

XMLHttpRequest.open(method, url, async, [username], [password])

此函数打开客户端以对指定的url发起method请求。方法可以是GET、HEAD、POST、PUT、PATCH或DELETE。async参数必须为false。

可选的username和password参数可用于对服务器进行身份验证。

与在Web浏览器中不同，通过XMLHttpRequest对象发起的请求仅在前台运行。不需要安装异步接收数据的事件处理器。将async设置为false时，对send()的调用将在完全收到响应之前等待。

Number XMLHttpRequest.readyState

此属性保存客户端的当前状态。可能的值有XMLHttpRequest.UNSENT、OPENED、HEADERS_RECEIVED、LOADING和DONE。考虑到同步的send()模式，中间状态HEADERS_RECEIVED和LOADING不会对测试脚本可见。

String XMLHttpRequest.responseText

在请求成功的情况下，此属性保存服务器的响应。期望响应文本为UTF-8编码。以下是一个使用此属性来检查Web页面内容的示例

var client = new XMLHttpRequest();
client.open('GET', 'https://www.froglogic.com', false);
client.send();
test.compare(client.status, 200);
test.verify(client.response.indexOf("Testing") >= 0);

XMLHttpRequest.send([data], [boundary])

此函数初始化请求，方法为由XMLHttpRequest.open(method, url, async, [username], [password])指定的参数。如果请求方法是GET或HEAD，则忽略data参数。可选的boundary仅在发送表单数据时使用，设置键值对之间的分隔边界。

一个虚构的示例，演示通过REST API调用将客户添加到数据库中

var client = new XMLHttpRequest();
client.open("POST", "http://www.example.com/rest/CUSTOMER/", false);
client.send("<CUSTOMER><ID>60</ID><FIRSTNAME>Laura</FIRSTNAME><LASTNAME>Miller</LASTNAME><STREET>443 Seventh Av.</STREET><CITY>Lyon</CITY></CUSTOMER>");
test.compare(client.statusText, "Created");

此外，此函数可以使用HTTP POST 或 PUT 请求，根据FormData Web API发送FormData。以下示例显示了如何使用FormData将另一位客户添加到上面提到的同一数据库中。

var client = new XMLHttpRequest();
client.open("POST", "http://www.example.com/rest/CUSTOMER/", false);
client.setRequestHeader( "Content-type", "multipart/form-data" );

var data = new FormData();
data.append("id", "61");
data.append("firstname", "John");
data.append("lastname", "Smith");
data.append("street", "1301 Ferguson Rd");
data.append("city", "Sebastopol");

client.send(data);
test.compare(client.statusText, "Created");

以这种方式发送表单数据时，重要的是使用 XMLHttpRequest.setRequestHeader(header, value) 并将媒体类型通过 Content-type 设置为 multipart/form-data。设置 Content-type 标头对于数据被服务器正确解释至关重要。

可以在HTTP请求体中设置一个自定义边界，用于分隔键和值，并避免任何随机边界。此边界作为send方法的第二个可选参数提供。该边界不应超过70个字符，并且应仅包含US-ASCII字符集中的字符。当使用UTF-8字符时，请相应地设置Content-Type头中的charset。

client.send(data, "CUSTOMBOUNDARY");

有关如何处理此类数据的更多详细信息，请参阅FormData对象部分。

XMLHttpRequest.setRequestHeader(header, value)

此函数将一个标题添加到请求头列表中；如果 header 已经在头列表中，则将值与 value 结合。以下示例显示了显式设置发送的消息类型。

client.setRequestHeader("Content-Type", "text/plain;charset=UTF-8");
client.send(message);

Number XMLHttpRequest.status

该只读属性包含上一个请求的HTTP状态码。例如，如果GET请求成功，则值为200。有关完整列表，请参阅状态码注册处。

String XMLHttpRequest.statusText

该只读属性包含上一个请求的HTTP状态文本。例如，如果GET请求成功，则值为“OK”。有关完整列表，请参阅状态码注册处。

FormData Object

FormData对象提供了一个基于键值的数据容器，用于处理表单收集的数据。它类似于FormData Web API。大多数函数都已实现，以使测试套件能够使用 XMLHttpRequest.send([data], [boundary]) 函数来准备、处理和发送FormData。

以下示例显示了创建FormData对象以及使用其所有方法的用法。以下将跟随相应的描述。

var data = new FormData();

// appending values
data.append("key", "value 1");
data.append("key", "value 2");
var valueList = data.getAll("key");

// looking for values
if (data.has("key")) {
  // ...
}

// overwriting values
data.set("key", "new value");
var singleValue = data.get("key");

// removing values
data.remove("key");

data.append(key, value)

此方法可以根据 key 标识的类型追加 value。FormData容器可以为单个键存储多个值。所有值都被处理为字符串。处理其他类型需要额外的解析。

也可以追加文件。与FormData API文档中的Web API不同，Squish利用由 File对象 提供的File API。以下示例将一个纯文本文件追加到FormData实例中。

var data = new FormData();
var file = File.open("data.txt","r");
data.append("test.txt", file.read());
file.close();

有关文件对象及其方法的更多详细信息，请参阅File.File.open(fileName)、String file.read()和file.close()。

String data.get( key)

获取使用data.append(key, value)或data.set(key, value)存储的单个值。对于包含多个值的键，它返回单个值或第一个存储的值。

ListOfString data.getAll( key)

以列表形式返回给定键的所有值。

Boolean data.has(key)

如果容器具有key的值，则返回true，否则返回false。

data.remove( key)

移除key的所有值。如果存储了多个值，则都会被移除。

data.set(key, value)

使用提供的数据覆盖已存储的key-value对。如果在之前有多个值，则在添加新值之前将移除所有值。