Home · All Namespaces · All Classes · Grouped Classes · Modules · Functions

QtUiTest Scripting Language

The QtUiTest language is based upon QtScipt which is based upon the JavaScript (ECMA-262) standard. To use QtUiTest only a brief knowledge about JavaScript should be sufficient to write 95% of the testcases. When more specific functions are required a book or Internet search is the next step to take.

This document introduces the basic concepts of the QtUiTest scripting language and should be read by a novice with no previous (or minor) knowledge of scripting languages. If you already know how to write JavaScript it is probably safe to skip this document and just focus on the QtUiTest API which introduces new functions that are used to write tests.

This manual contains:

• Grammar
• Variables
• Operators
• Expressions
• Statements
• Objects
• Functions and Methods
• Variables and data types
• Scope
• Type
• Operators
• Arithmetic or computational
• Comparison
• boolean
• string
• assignment
• special
• Statements
• Conditionals
• if...else
• switch
• Loops
• for
• do...while
• while
• break and continue
• Object manipulation
• for...in
• with
• Comments
• Functions
• Defining functions
• calling functions
• Objects
• Properties
• Methods
• Creating Objects
• direct instance of an object
• prototype of an object

Grammar

QtScript code, much like other programming languages, is made up of statements which serve to make assignments, compare values, and execute other sections of code. By and large, programmers will already be familiar with JavaScript's usage of variables, operators, and statements. Following, we will look at each of these elements in a bit more detail.

Variables

Labels which refer to a changeable value.

Example: total may possess a value of 100.

Operators

Actors which can be used to calculate or compare values.

Example 1: Two values may be summed using the addition operator (+); total+tax

Example 2: Two values may be compared using the greater-than operator (>); total>200

Expressions

Any combination of variables, operators, and statements which evaluate to some result. In English parlance this might be termed a "sentence" or even a "phrase", in that grammatical elements are combined into a cogent meaning.

Example 1: total=100;

Example 2: if (total>100)

Statements

As in English, a statement pulls all grammatical elements together into a full thought. JavaScript statements may take the form of conditionals, loops, or object manipulations. It is good form to separate statements by semicolons, although this is only mandatory if multiple statements reside on the same line.

Example 1: if (total>100) {statements;} else {statements;}

Example 2: while (clicks<10) {statements;}

Objects

Containing constructs which possess a set of values, each value reflected into an individual property of that object. Objects are a critical concept and feature of JavaScript. A single object may contain many properties, each property which acts like a variable reflecting a certain value. JavaScript can reference a large number of "built-in" objects which refer to characteristics of a Web document. For instance, the document object contains properties which reflect the background color of the current document, its title, and many more.

Functions and Methods

A JavaScript function is quite similar to a "procedure" or "subroutine" in other programming languages. A function is a discrete set of statements which perform some action. It may accept incoming values (parameters), and it may return an outgoing value. A function is "called" from a JavaScript statement to perform its duty. A method is simply a function which is contained in an object. For instance, a function which closes the current window, named close(), is part of the window object; thus, window.close() is known as a method.

Variables and data types

Variables store and retrieve data, also known as "values". A variable can refer to a value which changes or is changed. Variables are referred to by name, although the name you give them must conform to certain rules. A JavaScript identifier, or name, must start with a letter or underscore ("_"); subsequent characters can also be digits (0-9). Because JavaScript is case sensitive, letters include the characters "A" through "Z" (uppercase) and the characters "a" through "z" (lowercase). Typically, variable names are chosen to be meaningful regarding the value they hold. For example, a good variable name for containing the total price of goods orders would be total.

Scope

When you assign a new variable to an initial value, you must consider the issue of scope. A variable may be scoped as either global or local. A global variable may be accessed from any JavaScript on the page. A local variable may only be accessed from within the function in which it was assigned.

Commonly, you create a new global variable by simply assigning it a value:

    newVariable=5;

However, if you are coding within a function and you want to create a local variable which only scopes within that function you must declare the new variable using the var statement:

    function myFunction()
    {
        var loop=1;
        total=0;
        ...additional statements...
    }

In the example above, the variable loop will be local to newFunction(), while total will be global to the entire page.

Type

A value, the data assigned to a variable, may consist of any sort of data. However, JavaScript considers data to fall into several possible types. Depending on the type of data, certain operations may or may not be able to be performed on the values. For example, you cannot arithmetically multiply two string values. Variables can be these types:

That said, JavaScript is a loosely typed language -- you do not have to specify the data type of a variable when you declare it, and data types are converted automatically as needed during script execution. By and large, you may simply assign any type of data to any variable. The only time data typing matters is when you need to perform operations on the data. Certain operators behave differently depending on the type of data being dealt with. For example, consider the + operator:

Operators

Operators take one or more variables or values (operands) and return a new value; e.g. the '+' operator can add two numbers to produce a third. You use operators in expressions to relate values, whether to perform arithmetic or compare quantities. Operators are divided into several classes depending on the relation they perform:

Arithmetic or computational

Arithmetic operators take numerical values (either literals or variables) as their operands and return a single numerical value. The standard arithmetic operators are:

Comparison

A comparison operator compares its operands and returns a logical value based on whether the comparison is true or not. The operands can be numerical or string values. When used on string values, the comparisons are based on the standard lexicographical (alphabetic) ordering.

boolean

Boolean operators are typically used to combine multiple comparisons into a conditional expression. For example, you might want to test whether (total>100) AND (stateTax=true). A boolean operator takes two operands, each of which is a true or false value, and returns a true or false result.

string

Strings can be compared using the comparison operators. Additionally, you can concatenate strings using the + operator.

assignment

The assignment operator (=) lets you assign a value to a variable. You can assign any value to a variable, including another variable (whose value will be assigned). Several shorthand assignment operators allow you to perform an operation and assign its result to a variable in one step.

special

Several JavaScript operators, rarely used, fall into no particular category. These operators are summarized below.

Statements

Statements define the flow of a script, known as "program flow." A statement, like a fully grammatical English sentence, is made up of smaller expressions which, altogether, evaluate into a cogent meaning. In JavaScript, statements are organized as either conditionals, loops, object manipulations, and comments.

Good practice suggests that each JavaScript statements should be terminated with a semicolon (;). This is often not strictly necessary, as a new line also serves to separate statements, but when multiple statements reside on the same line the semicolon delimiter is mandatory.

A set of statements that is surrounded by braces is called a block. Blocks of statements are used, for example, in functions and conditionals.

Normally statements are executed sequentially: x = 1; y = 2; z = x + y; but this can be altered by some statements which test a condition and branch or loop according to the result.

Conditionals

Conditional statements direct program flow in specified directions depending upon the outcomes of specified conditions. These tests are a major influence on the order of execution in a program.

if...else

As seen in many programming languages, if the condition evaluates to true then the block of statements1 is executed. Optionally, an else clause specifies a block of statements2 which are executed otherwise. You may omit the else clause if there are no statements which need to be executed if the condition is false.

    if (condition)
     { statements1; }
    else
     { statements2; }

switch

Commonly known as a "case statement," switch matches an expression with a specified case, and executes the statements defined for that case. In essence, the switch statement is a sort of shorthand for combining many implied if statements together.

    switch (expression){
       case label :
          statement;
          break;
       case label :
          statement;
          break;
       ...
       default : statement;
    }

For example, imagine that you wanted to execute different sets of statements depending on whether favoritePet was "dog," "cat," or "iguana." Note that the break; statement prevents any cases below the match from being executed. The default case is matched if none of the cases match the expression.

    switch (favoritePet){
       case "dog" :
          statements;
          break;
       case "cat" :
          statements;
          break;
       case "iguana" :
          statements;
          break;
       default : statements;
    }

Loops

for

The venerable for loop repeatedly cycles through a block of statements until a test condition is false. Typically, the number of times a loop is repeated depends on a counter. The JavaScript for syntax incorporates the counter and its increments:

    for (initial-statement; test; increment)
     { statements; }

The initial-statement is executed first, and once only. Commonly, this statement is used to initialize a counter variable. Then the test is applied and if it succeeds then the statements are executed. The increment is applied to the counter variable and then the loop starts again. For instance, consider a loop which executes 10 times:

    for (i=0; i<10; i++)
     { statements; }

do...while

Another loop, a do...while statement executes a block of statements repeatedly until a condition becomes false. Due to its structure, this loop necessarily executes the statement at least once.

    do
     { statements;}
    while (condition)

while

In similar fashion as the do...while statement, the while statement executes its statement block as long as the condition is true. The main difference between while and do...while, aside from the fact that only while is supported in all JavaScript versions, is that a while loop may not execute the statements even once if the condition is initially false.

    while (condition)
     { statements; }

break and continue

Both of these statements may be used to "jump the tracks" of an iterating loop. When used within the statement block of a loop, each statement behaves slightly differently:

Object manipulation

for...in

The sometimes confusing for...in statement is used to cycle through each property of an object or each element of an array. The idea is that you may want to execute a statement block which operates on every property or element.

    for (variable in object)
     { statements; }

Imagine, for example, that an object named wine1 has five properties: vineyard, year, varietal, alcohol, and color. You want to output the value of each property, as if producing a record from a database.

    var record = "Wine 1<br><br>"
    for (var prop in wine1)
     {record += prop + " = " + wine1[prop] + "<BR>"}
    record += "<br>"
    document.write(record)

with

The with statement serves as a sort of shorthand, allowing you to execute a series of statement who all assume a specified object as the reference. In other words, the object specified in the with statement is used as the default object whenever a property is encountered with no object specified.

    with (object)
     { statements; }

Comments

Despite the fact that comments are purely optional, they can easily be a crucial part of your program. Comments can explain the action, like a color commentary, which can be a great help in understanding the code. Whether as a teaching tool or to simply remind yourself what the code does, comments are best sprinkled liberally throughout a program. Remember, comments are for humans, so write them that way!

Comments can also be used for debugging -- you can comment "out" sections of code to prevent them from being executed. In doing so you may learn more about why a certain problem is occurring in your program.

Because JavaScript must ignore comments, there is an appropriate syntax for demarcating text as a comment. For single line comments, simply precede the line with two backslashes. For multi-line comment blocks, begin the comment with / * and close with * /.

    / / A lonely ol' single line comment

    /* A dense thicket of commentary, spanning many captivating lines
    of explanation and intrigue. */

Functions

A function groups together a set of statements under a named subroutine. This allows you to conveniently "call" the function whenever its action is required. Functions are a fundamental building block of most JavaScript programs, so you'll become quite familiar with their use. Before you can call on a function, of course, you must first create it. We can break down the use of functions, then, into two logical categories: defining functions and calling functions.

Defining functions

The function definition is a statement which describes the function: its name, any values (known as "arguments") which it accepts incoming, and the statements of which the function is comprised.

    function funcName(argument1,argument2,etc)
    { statements; }

A function doesn't necessarily require arguments, in which case you need only write out the parenthesis; e.g. funcName(). If you do specify arguments, those arguments will be variables within the function body (the statements which make up the function). The initial values of those variables will be any values passed on by the function call.

Some functions may return a value to the calling expression. The following function accepts two arguments, x and y, and returns the result of x raised to the y power:

    function raiseP(x,y)
    {
        total=1;
        for (j=0; j<y; j++)
        {
            total*=x;
        }
        return total; //result of x raised to y power
    }

calling functions

A function waits in the wings until it is called onto the stage. You call a function simply by specifying its name followed by a parenthetical list of arguments, if any:

    clearPage();

    boldblink("Call me gaudy!");

Functions which return a result should be called from within an expression:

    total=raiseP(2,8);

    if (raiseP(tax,2)<100) ...

Objects

An object is a "package" of data; a collection of properties (variables) and methods (functions) all classed under a single name. For example, imagine that there was an object named car. We could say that the car object possesses several properties: make, model, year, and color, for example. We might even say that car possesses some methods: go(), stop(), and reverse(). Although car is obviously fictional, you can see that its properties and methods all relate to a common theme.

In JavaScript you may create your own objects for storing data. More commonly, though, you will use the many "built-in" objects which allow you to work with, manipulate, and access the Web page and Web browser. This set of pre-existing objects is known as the "Document Object Model".

Properties

Access the properties of an object with a simple notation: objectName.propertyName. Both the object name and property name are case sensitive, so watch your typing. Because a property is essentially a variable, you can create new properties by simply assigning it a value. Assuming, for instance, that carObj already exists (we'll learn to create a new object shortly), you can give it properties named make, model, and year as follows:

    carObj.make="Toyota";
    carObj.model="Camry";
    carObj.year=1990;
    document.write(carObj.year);

A JavaScript object, basically, is an array. If you're familiar with other languages you probably recognize an array as a collection of values residing within a single named data structure. You can access an object's properties either using the objectName.propertyName syntax illustrated above, or by using an array syntax:

    carObj["make"]="Toyota";
    carObj["model"]="Camry";
    document.write(carObj["year"]);

Methods

Unlike a basic data array, an object can also contain functions, which are known as methods when part of an object. You call a method using the basic syntax: objectName.methodName(). Any arguments required for the method are passed between the parentheses, just like a normal function call.

For example, the window object possesses a method named close(), which simply closes the specified browser window:

    window.close();

Creating Objects

Most of the time you will be referencing objects which are built-in to the DOM. However, you may want to create your own objects for storing data within a JavaScript program. There are several ways to create a new object, but we'll look at two: creating a direct instance of an object and creating an object prototype.

direct instance of an object

Despite the awkward sound name, a "direct instance of an object" simply means creating a new single object, such as myPetDog:

     myPetDog=new Object();
     myPetDog.name="Barney";
     myPetDog.breed="beagle";
     myPetDog.year=1981;

Assigning a method to your new object is also simple. Assume that you already have coded a function named woof(), which causes a barking sound to play:

    myPetDog.woof=woof;

prototype of an object

Sometimes, you'll want to create a "template" or prototype of an object. This does not create an actual instance of the object, but defines the structure of the object. In the future, then, you can quickly stamp out a particular instance of the object. Suppose that instead of myPetDog, you created a prototype object named petDog. This object could then be a template for a particular pet dog object. First, create a function which defines the petDog structure:

    function petDog(name, breed, year)
    { this.name = name;
      this.breed = breed;
      this.year = year;
    }

Now that the petDog prototype has been set, you can quickly create single instances of a new object based on the petDog structure:

    myPetDog=new petDog("barney","beagle",1981);
    yourPetDog=new petDog("max","terrier",1990);