Skip to main content

SWELL/Web - Language Manual

Still under construction! Still under construction! Still under construction!

This guide describes the SWELL/Web language which is a DSL used to describe a suite of tests to the SWELL/Web interpreter.

Test Suite

A test-suite is a text-file containing a SWELL/Web script as described here. Each test-suite may contain several tests. A test consists of a label followed by a series of (one or more) statements. Examples of this structure can be seen in ValidatorScript.txt and SWELLWebHelloWorld.txt.

Statements

The table below lists and describes all SWELL/Web statements. Each description begins with the formal syntax definition, followed by a plain-language explanation and examples as applicable. Observe that each statement ends with a full-stop. The formal syntax may also contain hyperlinks to further details. SWELL/Web statements are format-free, so whitespace characters (space, tab, newline, etc.) may be freely used between words as needed. All SWELL/Web statements must be terminated with a ";" (semocolon).

The formal syntax definitions in the table below use the notation commonly used to describe grammars. All quoted strings (e.g. "double", "=", etc.) are literals, [...] depicts an optional element, (...|...) represents alternatives, and {...} represents 0 or more occurrences of the contents.

StatementDescriptionGrammar-Tree Name
Assignment
VAR "=" SWELL-Expression ";"
An assignment statement sets the value of a user-defined variable. The SWELL/Web interpreter is written in JavaScript (Rhino) so user-defined variables are untyped. User-defined variables do not have to be declared before use, but must be assigned to before their value is used. Examples:
x = 3.5;
message = "user01";
nbrOfUsers = 5;
The value assigned can be any SWELL-Expression as defined below.
stmtAssignment
Choose
"choose" SWELL-Expression ("from" | "of" | "in") "the" Tag-Query ";"
Chooses (selects) an option from a drop-down list. Examples:
choose "Rose" from the "Flower-Name" <select>;
choose 2 from the <select> in the first <table>;
The expression provided (after the keyword choose) is evaluated at runtime, and processed as follows. If its typeof is number it is used as a (0-based) index to select the nth option, otherwise the string value of the result is used to select a matching option.
stmtChoose
Click
[("double" | "right")] "click" "the" Tag-Query ";"
Performs a mouse-click over the middle of the specified web-element. Example:
click the "Ok" <button>;
click the <a> in the 3rd <td> in the last <tr> in the <table>;
The italicised part of the statements is the Tag-Query.
stmtClick
Close
"close" ";"
Closes the current browser-window.
stmtClose
Delay
"delay" Time-Duration ";"
Causes the test execution to be delayed by the specified duration. Examples:
delay 3 seconds;
delay 500 ms;
delay 5 milli seconds;
stmtDelay
Exec
"exec" INLINE-CODE ";"
Exectues the JavaScript code in the specified INLINE-CODE. Example:
exec {{ java.lang.System.gc(); }};
Since the JavaScript is being executed by the JVM's Rhino JavaScript engine, the Java API's classes are accessible as in the example above. User-defined variables may also be accessed (but not assigned) by using the ${...} notation.
stmtExec
Fail
"fail" ["the"] "test" ["with"] "message" STRING-LITERAL 
    [("if" | "unless") SWELL-Expression ["within" Time-Duration]] ";"
Specifies a condition (and associated message) for a negative test outcome. Examples:
fail the test with message "No client found";
fail test message "Connect failed" if the 
    first <text> contains "Error";
fail test with message "Bad parse result" unless 
    the 2nd <label> contains "Ok" within 5 seconds;
stmtFail
Go
"go" ("to" SWELL-Expression | "back" | "forward") ";"
Makes the browser navigate to a web-site, backward, or forward respectively. Example:
go to "http://swell.java.net/";
go to theWebSite;
go back;
When the go to form is used (as in the first two examples above), the expression is evaluated at runtime, and its string value is used as the url.
stmtGo
If
"if" SWELL-Expression "then" Statement-List 
    ["else" Statement-List] "end" ["if"] ";"
A conditional control flow statement. Example:
if nbr > 3 then 
  pause "Done!"; 
end if;

if the <text> contains "Error" then 
  fail the test with message "No connection"; 
  nbrOfFailures = nbrOfFailures + 1;
else
  nbrOfSuccesses = nbrOfSuccesses + 1;
end if;
stmtIf
Key-Text
"key" SWELL-Expression "into" "the" Tag-Query ";"
Keys the supplied text into the specified web-element. The expression provided is evaluated at runtime and its string value is inserted into the web-element. Examples:
key "john@john.com" into the first <input>;
key thePassword into the "password" <input>;
key userNames[i] into the first <input> in the <form>;
stmtKeyText
Pause
"pause" SWELL-Expression ";"
Pops up a blocking dialog with the specified message. The expression provided is evaluated at runtime and its string value is used as the message. Examples:
pause "Start client NOW";
pause nbrFailures + " tests failed!";
pause lastMessage;
The pause statement, unlike print below, causes execution of the test to be suspended till the user clicks the popup's ok button.
stmtPause
Print
"print" SWELL-Expression ";"
Prints the specified message on the console. The expression provided is evaluated at runtime and its string value is used as the message to be printed. Examples:
print "Connection established";
print nbrFailures + " tests failed!";
print element.getText();
stmtPrint
Quit
"quit" ";"
Closes all browser windows, and exits the test environment.
stmtQuit
Trace
"trace" ("on" | "off") ";"
Starts or stops tracing of tests. Examples:
trace on;
trace off;
Tracing is off by default, and any number of trace statements may be inserted as needed in a SWELL/Web script.
stmtTrace
Use
"use" ("chrome" STRING-LITERAL | "firefox" [STRING-LITERAL] | 
    "ie" | "opera") ";"
Starts the chosen browser. The string supplied for chrome is the relative location of the chrome driver. The optional string supplied for firefox is the profile name.
stmtUse
Wait
"wait" [Time-Duration] (["for"] [("frame" | "dialog")] STRING-LITERAL | 
    "until" SWELL-Predicate) ";"
Causes execution to be delayed till the named frame/dialog appears or the specified event occurs. An optional maximum wait time can also be specified. Examples:
wait for dialog "Error";
wait 3.5 s until the "Status" <label> contains "Done!";
stmtWait
While
"while" SWELL-Expression "do" Statement-List "end" ["while"] ";"
The usual looping statement. Example:
while any "UserData" <form> exists do
    key data[i] into the first <text> in the "UserData" <form>;
    click the "Next" <button> in the "UserData" <form>;
    i = i + 1;
end while;
stmtWhile

SWELL-Expression

A SWELL-Expression is used in many statements to provide a value computed at run time. A SWELL-Expression is not typed, and may contain any JavaScript value (including arrays, objects, and functions). The grammar of a SWELL-Expression is defined as follows:

SWELL-Expression: Expression2 ["?" SWELL-Expression ":" SWELL-Expression]

Expression2: Expression3 {("||" | "or") Expression3}

Expression3: Expression4 {("&&" | "and") Expression4}

Expression4: Expression5 [("===" | "!==") Expression5]

Expression5: Expression6 [(">=" | ">" | "<" | "<=") Expression6]

Expression6: Expression7 {("+" | "-") Expression7}

Expression7: Expression8 {("*" | "/" | "%") Expression8}

Expression8: (Expression8 Refinement Invocation
| Expression8 Refinement 
| "typeof" SWELL-Expression
| "!" SWELL-Expression
| "+" NUMBER
| "-" NUMBER
| "(" SWELL-Expression ")"
| SWELL-Predicate
| ("the" | "all" ["the"]) Tag-Query
| IDENT
| literal
)

Refinement: (("." IDENT) | "[" SWELL-Expression "]")

Invocation: "(" [SWELL-Expression {"," SWELL-Expression}] ")"

Tag-Query

A Tag-Query is used to identify one or more web-elements from the browser's display. In JavaScript terms, it is an array (with 0 or more elements depending on the query used) of WebDriver objects. Its grammar is defined as follows:

Tag-Query: Tag-Query-Selection {("in" | "after" | "before") "the" Tag-Query-Selection}

Tag-Query-Selection: [Tag-Query-Position] [STRING-LITERAL] HNAME 
    ["with" Tag-Query-Attribute-Expression]

Tag-Query-Position: ("first" | "last" | ORDINAL)

Tag-Query-Attribute-Expression: Tag-Query-Attribute-Expression2 
    {("and" | "or") Tag-Query-Attribute-Expression2}

Tag-Query-Attribute-Expression2: ( "(" Tag-Query-Attribute-Expression ")" | 
    HNAME ("=" | "==" | "!=" | "<>") literal)

A Tag-Query-Selection is used to select one web-element from a list of web-elements by progressive sub-setting from all the web-elements contained in the browser's DOM.

The Tag-Query-Position selects one web-element from a list by its position. The STRING-LITERAL is used to sub-set web-elements by specifying the text, name attribute, value attribute, or id. The HNAME filters elements by type (HTML tag name). The last optional part ("with" ...) selects elements satisfying a certain relation on the attribute values.

A Tag-Query-Position is used to specify the position of a web-element in a list of web-elements.

A Tag-Query-Attribute-Expression is an expression built from a tag's attribute values.

A Tag-Query-Attribute-Expression2 is a helper rule for Tag-Query-Attribute-Expression.

SWELL-Predicate

A SWELL-Predicate is used to provide a (boolean) answer to certain questions about the current state of the GUI. it is defined as follows:

SWELL-Predicate: ( Tag-Functional-Predicate
| Tag-Dynamics-Predicate
| Tag-Existential-Predicate
| Tag-Visual-Predicate
)

Tag-Functional-Predicate: ("the" | "all" | "any" | "no") Tag-Query 
    ("contains" | "excludes" | "matches" | "equals" | "has") SWELL-Expression

Tag-Dynamics-Predicate: (("any" | "the") Tag-Query 
    ("appear" | "appears") | "the" Tag-Query "disappears")

Tag-Existential-Predicate: ("any" | "no") Tag-Query ("exist" | "exists")

Tag-Boolean-Predicate: "the" Tag-Query "is" ["not"] 
    ("selected" | "enabled" | "displayed")

A tag functional predicate is used to test a list of web-elements and determine how many (the, any, all, no) of them satisfy the condition specified. The condition may currently include the following: contains (text), excludes (text), matches (text), equals (text), and has/have (expression).

A tag dynamics predicate is used to test if any web-element has appeared or disappeared over the interval sepecified (explicitly or implicitly).

A tag existential predicate is used to test if a web-element exists.

A tag visual predicate is used test he visual state (selected, enabled, displayed) of a web-element.

Statement-List

A Statement-List represents a list of statements, and is defined as follows:

(Assignment | Click | ... While) {(Assignment | Click | ... While)}

literal

A literal represents any of the literal value types:

("false" | NUMBER | STRING-LITERAL | "true" | JS-Array-Literal | JS-Object-Literal)

JS-Array-Literal

The usual notation used for a JavaScript array literal.

JS-Object-Literal

The usual notation used for a JavaScript object literal.

Time-Duration

A time-duration can take any of the following forms (where 999 represents a number with or without a decimal point):

  • 999 s
  • 999 ms
  • 999 second
  • 999 seconds
  • 999 milli second
  • 999 milli seconds

In the above forms, second and seconds can be used interchangeably irrespective of the magnitude of the duration.

STRING-LITERAL

A literal string represented by the following regular-expression:
\"((\\\\[\'\"tfnrb\\\\])|[^\"\\\\])*+\"

INLINE-CODE

Several SWELL statements allow the use of embedded JavaScript code. Embedded code must be enclosed within doubled curly-braces, as in the following examples:

  • {{java.lang.System.gc()}} - used only for its side-effect; the returned value (if any) is ignored
  • {{"Window-" + clientID}} - returns a String value that is used by the embedding statement

Examples in the table above show some uses of inline embedded code. Since the JavaScript is executed by the JVM's Rhino engine, the Java API's classes are accessible. User-defined variables may also be accessed (but not assigned) using the ${...} notation.

FLOAT

A floating-point number represented by the following regular-expression:
-?(\\d+\\.\\d*|\\d*\\.\\d+)([eE][+-]?\\d+)?[fFdD]?

INT

An integer represented by the following regular-expression:
[-]?\\d+[Ll]?

HNAME

A HTML tag name represented by the following regular expression:
<[a-zA-Z]+>

IDENT

A user-defined variable name represented by the following regular expression:
[a-zA-Z][a-zA-Z0-9]*

ORDINAL

A position indicator defined by the following regular expression
1st|2nd|3rd|4th|5th|6th|7th|8th|9th|[1-9][0-9]*(1st|2nd|3rd|4th|5th|6th|7th|8th|9th|0th)

 
 
Close
loading
Please Confirm
Close