gwen-web/gwen.web.eval/WebContext

WebContext

class WebContext(options: GwenOptions, envState: EnvState, driverManager: DriverManager) extends EvalContext with LazyLogging with WebSessionEventListener

The web evaluatioin context.

class EvalContext
trait SimilaritySupport
trait TemplateSupport
trait DecodingSupport
trait ScriptSupport
trait SQLSupport
trait JsonPathSupport
trait XPathSupport
trait RegexSupport
trait Interpolator
class Environment
trait LazyLogging
class Object
trait Matchable
class Any

Value members

Concrete methods

override def addErrorAttachments(step: Step, failure: Failed): Step

Add a list of error attachments to the given step including the current screenshot and all current error attachments.

Add a list of error attachments to the given step including the current screenshot and all current error attachments.

Value parameters:
failure

the failed status

Definition Classes
EvalContext
def bindAndWait(element: String, action: String, value: String): Unit

Binds the given element and value to a given action (element/action=value) and then waits for any bound post conditions to be satisfied.

Binds the given element and value to a given action (element/action=value) and then waits for any bound post conditions to be satisfied.

Value parameters:
action

the action to bind the value to

element

the element to bind the value to

value

the value to bind

def boundAttributeOrSelection(element: String, selection: Option[DropdownSelection]): () => String
def captureCurrentUrl: String
def captureElementScreenshot(binding: LocatorBinding, name: String): Option[File]

Captures an element screenshot and adds it to the attachments list.

Captures an element screenshot and adds it to the attachments list.

def captureScreenshot(unconditional: Boolean, name: String): Option[File]

Captures the current screenshot and adds it to the attachments list.

Captures the current screenshot and adds it to the attachments list.

def checkElementState(binding: LocatorBinding, state: ElementState, negate: Boolean, message: Option[String]): Unit

Checks the current state of an element.

Checks the current state of an element.

Value parameters:
binding

the locator binding of the element

message

optional assertion error message

negate

whether or not to negate the check

state

the state to check

override def close(): Unit

Closes the context and all browsers and associated web drivers (if any have loaded).

Closes the context and all browsers and associated web drivers (if any have loaded).

Definition Classes
Environment
def close(name: String): Unit

Closes a named browser and associated web driver.

Closes a named browser and associated web driver.

def closeChild(): Unit

Closes the last child window.

Closes the last child window.

def closeWindow(occurrence: Int): Unit

Closes the tab or window occurrence.

Closes the tab or window occurrence.

Value parameters:
occurrence

the tag or window occurrence to close (primary is 0, first opened is occurrence 1, 2nd is 2, ..)

def compare(name: String, expected: String, actual: () => String, operator: ComparisonOperator, negate: Boolean, nameSuffix: Option[String], message: Option[String]): Unit

Gets the actual value of an attribute and compares it with an expected value or condition.

Gets the actual value of an attribute and compares it with an expected value or condition.

Value parameters:
actual

the actual value of the element

expected

the expected value, regex, xpath, or json path

message

optional error message to use

name

the name of the attribute being compared

nameSuffix

optional name suffix

negate

true to negate the result

operator

the comparison operator

Returns:

true if the actual value matches the expected value

def deselectByIndex(binding: LocatorBinding, index: Int): Unit

Deselects a value in a dropdown (select control) by index.

Deselects a value in a dropdown (select control) by index.

Value parameters:
binding

the locator binding

index

the index to select (first index is 0)

def deselectByValue(binding: LocatorBinding, value: String): Unit

Deselects a value in a dropdown (select control) by value.

Deselects a value in a dropdown (select control) by value.

Value parameters:
binding

the locator binding

value

the value to select

def deselectByVisibleText(binding: LocatorBinding, value: String): Unit

Deselects a value in a dropdown (select control) by visible text.

Deselects a value in a dropdown (select control) by visible text.

Value parameters:
binding

the locator binding

value

the value to select

def dragAndDrop(sourceBinding: LocatorBinding, targetBinding: LocatorBinding): Unit
override def dsl: List[String]

Adds web engine dsl steps to super implementation. The entries returned by this method are used for tab completion in the REPL.

Adds web engine dsl steps to super implementation. The entries returned by this method are used for tab completion in the REPL.

Definition Classes
EvalContext
override def evaluateJS(javascript: String, params: Any*): Any

Executes a javascript expression on the current page through the web driver.

Executes a javascript expression on the current page through the web driver.

Value parameters:
javascript

the script expression to execute

params

optional parameters to the script

Definition Classes
ScriptSupport
def executeJS(javascript: String, params: Any*)(implicit takeScreenShot: Boolean): Any

Injects and executes a javascript on the current page through web driver.

Injects and executes a javascript on the current page through web driver.

Value parameters:
javascript

the script expression to execute

params

optional parameters to the script

takeScreenShot

true to take screenshot after performing the function

override def formatJSReturn(javascript: String): String

Appends a return keyword in front of the given javascript expression in preparation for execute-with-return (since web driver requires return prefix).

Appends a return keyword in front of the given javascript expression in preparation for execute-with-return (since web driver requires return prefix).

Value parameters:
javascript

the javascript function

Definition Classes
ScriptSupport
def getAttribute(name: String): String

Resolves a bound attribute value from the visible scope.

Resolves a bound attribute value from the visible scope.

Value parameters:
name

the name of the bound attribute to find

override def getBoundReferenceValue(name: String): String

Gets a bound value from memory. A search for the value is made in the following order and the first value found is returned:

Gets a bound value from memory. A search for the value is made in the following order and the first value found is returned:

  • Web element text on the current page
  • Currently active page scope
  • The top scope
  • Settings
Value parameters:
name

the name of the bound value to find

Definition Classes
EvalContext
def getCachedWebElement(element: String): Option[WebElement]

Gets a cached web element.

Gets a cached web element.

Value parameters:
element

the name of the web element

Returns:

the cached web element

def getElementSelection(name: String, selection: DropdownSelection): Option[String]

Gets an element's selected value(s).

Gets an element's selected value(s).

Value parameters:
name

the name of the element

selection

text to get selected option text, value to get selected option value

Returns:

the selected value or a comma seprated string containing all the selected values if multiple values are selected.

def getElementText(binding: LocatorBinding): Option[String]

Gets the text value of a web element on the current page. A search for the text is made in the following order and the first value found is returned:

Gets the text value of a web element on the current page. A search for the text is made in the following order and the first value found is returned:

  • Web element text
  • Web element text attribute
  • Web element value attribute If a value is found, its value is bound to the current page scope as name/text.
Value parameters:
binding

the locator binding

def getLocatorBinding(name: String): LocatorBinding

Gets a named locator binding.

Gets a named locator binding.

Value parameters:
name

the name of the web element

def getLocatorBinding(name: String, optional: Boolean): Option[LocatorBinding]

Gets a named locator binding.

Gets a named locator binding.

Value parameters:
name

the name of the web element

optional

true to return None if not found; false to throw error

def getPopupMessage: String

Gets the message of an alert of confirmation popup.

Gets the message of an alert of confirmation popup.

Returns:

the alert or confirmation message

def getTitle: String

Gets the title of the current page in the browser.

Gets the title of the current page in the browser.

def handleAlert(accept: Boolean): Unit

Handles an alert (pop-up)

Handles an alert (pop-up)

Value parameters:
accept

true to accept; false to dismiss

def highlightElement(element: WebElement): Unit

Highlights and then un-highlights a browser element. Uses pure javascript, as suggested by https://github.com/alp82. The duration of the highlight lasts for gwen.web.throttle.msecs. The look and feel of the highlight is controlled by the gwen.web.highlight.style setting.

Highlights and then un-highlights a browser element. Uses pure javascript, as suggested by https://github.com/alp82. The duration of the highlight lasts for gwen.web.throttle.msecs. The look and feel of the highlight is controlled by the gwen.web.highlight.style setting.

Value parameters:
element

the element to highlight

def holdAndClick(modifierKeys: Array[String], clickAction: ElementAction, binding: LocatorBinding): Unit
def isDisplayed(webElement: WebElement): Boolean

Checks if an element is displayed.

Checks if an element is displayed.

def locateAndHighlight(binding: LocatorBinding): Unit

Locates a web element and highlights it.

Locates a web element and highlights it.

Value parameters:
binding

the locator binding

def maximizeWindow(): Unit

Maximizes the browser window.

Maximizes the browser window.

def moveToAndCapture(driver: WebDriver, webElement: WebElement): Unit
def newOrCurrentSession(): Unit

Starts a new session if there isn't one or stays in the current one.

Starts a new session if there isn't one or stays in the current one.

def noOfSessions(): Int

Gets the number of open sesions.

Gets the number of open sesions.

def noOfWindows(): Int

Gets the number of open windows.

Gets the number of open windows.

def performAction(action: ElementAction, binding: LocatorBinding): Unit
def performActionInContext(action: ElementAction, element: String, context: String): Unit

Performs and action on a web element in the context of another element.

Performs and action on a web element in the context of another element.

Value parameters:
action

description of the action

context

the name of the context element binding to find the element in

element

the name of the element to perform the action on

def refreshPage(): Unit

Refreshes the current page.

Refreshes the current page.

def reset(): Unit

Resets the driver context.

Resets the driver context.

override def reset(level: StateLevel): Unit

Resets the context for the given state level.

Resets the context for the given state level.

Definition Classes
Environment
def resizeWindow(width: Int, height: Int): Unit

Resizes the browser window to the given dimensions.

Resizes the browser window to the given dimensions.

Value parameters:
height

the height

width

the width

def scrollIntoView(binding: LocatorBinding, scrollTo: ScrollTo): Unit

Scrolls an element into view.

Scrolls an element into view.

Value parameters:
binding

the locator binding

scrollTo

scroll element into view, options are: top or bottom

def scrollIntoView(webElement: WebElement, scrollTo: ScrollTo): Unit

Scrolls the given web element into view.

Scrolls the given web element into view.

Value parameters:
scrollTo

scroll element into view, options are: top or bottom

webElement

the web element to scroll to

def selectByIndex(binding: LocatorBinding, index: Int): Unit

Selects a value in a dropdown (select control) by index.

Selects a value in a dropdown (select control) by index.

Value parameters:
binding

the locator binding

index

the index to select (first index is 0)

def selectByValue(binding: LocatorBinding, value: String): Unit

Selects a value in a dropdown (select control) by value.

Selects a value in a dropdown (select control) by value.

Value parameters:
binding

the locator binding

value

the value to select

def selectByVisibleText(binding: LocatorBinding, value: String): Unit

Selects a value in a dropdown (select control) by visible text.

Selects a value in a dropdown (select control) by visible text.

Value parameters:
binding

the locator binding

value

the value to select

def sendKeys(keysToSend: Array[String]): Unit
def sendKeys(binding: LocatorBinding, keysToSend: Array[String]): Unit
def sendKeys(elementBindingOpt: Option[LocatorBinding], keysToSend: Array[String]): Unit
def sendValue(binding: LocatorBinding, value: String, clearFirst: Boolean, clickFirst: Boolean, sendEnterKey: Boolean): Unit

Sends a value to a web element.

Sends a value to a web element.

Value parameters:
binding

the locator binding

clearFirst

true to clear field first (if element is a text field)

clickFirst

true to click field first (if element is a text field)

sendEnterKey

true to send the Enter key after sending the value

value

the value to send

override def sessionOpened(event: WebSessionEvent): Unit
Definition Classes
def switchToChild(): Unit

Switches to the first child window if one was just opened.

Switches to the first child window if one was just opened.

def switchToDefaultContent(): Unit

Switches to the top window / first frame

Switches to the top window / first frame

def switchToNewWindow(winType: WindowType): Unit

Starts and switches to a new tab or window.

Starts and switches to a new tab or window.

Value parameters:
winType

tab or window

def switchToParent(): Unit

Switches to the parent window.

Switches to the parent window.

def switchToSession(session: String): Unit

Switches the web driver session

Switches the web driver session

Value parameters:
session

the name of the session to switch to

def switchToWindow(occurrence: Int): Unit

Switches to a tab or window occurrence.

Switches to a tab or window occurrence.

Value parameters:
occurrence

the tag or window occurrence to switch to (primary is 0, first opened is occurrence 1, 2nd is 2, ..)

def tryMoveTo(webElement: WebElement): Unit
def waitForElementState(binding: LocatorBinding, state: ElementState, negate: Boolean): Unit

Waits the state of an element.

Waits the state of an element.

Value parameters:
binding

the locator binding of the element

negate

whether or not to negate the check

state

the state to wait for

def waitForText(binding: LocatorBinding): Boolean

Waits for text to appear in the given web element.

Waits for text to appear in the given web element.

Value parameters:
binding

the locator binding

def waitUntil(reason: String)(condition: => Boolean): Unit

Waits for a given condition to be true. Errors on time out after "gwen.web.wait.seconds" (default is 10 seconds)

Waits for a given condition to be true. Errors on time out after "gwen.web.wait.seconds" (default is 10 seconds)

Value parameters:
condition

the boolean condition to wait for (until true)

reason

a description of what is being waited on

def waitUntil(timeoutSecs: Option[Long], reason: String)(condition: => Boolean): Unit

Waits until a given condition is ready for an optional number of seconds. Errors on given timeout out seconds.

Waits until a given condition is ready for an optional number of seconds. Errors on given timeout out seconds.

Value parameters:
condition

the boolean condition to wait for (until true)

reason

a description of what is being waited on

timeoutSecs

optional number of seconds to wait before timing out

override def waitUntil(timeoutSecs: Long, reason: String)(condition: => Boolean): Unit

Waits until a given condition is ready for a given number of seconds. Errors on given timeout out seconds.

Waits until a given condition is ready for a given number of seconds. Errors on given timeout out seconds.

Value parameters:
condition

the boolean condition to wait for (until true)

reason

a description of what is being waited on

timeoutSecs

the number of seconds to wait before timing out

Definition Classes
EvalContext
def waitUntil(delayMsecs: Option[Long], timeoutSecs: Option[Long], reason: String)(condition: => Boolean): Unit

Waits until a given condition is ready for a given number of seconds using a given polling delay. Errors on given timeout out seconds.

Waits until a given condition is ready for a given number of seconds using a given polling delay. Errors on given timeout out seconds.

Value parameters:
condition

the boolean condition to wait for (until true)

delayMsecs

the polling delay (milliseconds)

reason

a description of what is being waited on

timeoutSecs

the number of seconds to wait before timing out

def waitUntil[T](reason: String, condition: ExpectedCondition[T]): Unit
def withWebDriver[T](function: WebDriver => T)(implicit takeScreenShot: Boolean): Option[T]

Invokes a function that performs an operation on the current web driver session and conditionally captures the current screenshot if the specified takeScreenShot is true.

Invokes a function that performs an operation on the current web driver session and conditionally captures the current screenshot if the specified takeScreenShot is true.

Value parameters:
function

the function to perform

takeScreenShot

true to take screenshot after performing the function

Inherited methods

def addAttachment(name: String, file: File): Unit
Inherited from:
Environment
def addBehavior(behavior: BehaviorType): BehaviorType

Adds current behavior.

Adds current behavior.

Inherited from:
Environment
def addScope(name: String): ScopedData

Gets a named data scope (creates it if it does not exist)

Gets a named data scope (creates it if it does not exist)

Value parameters:
name

the name of the data scope to get (or create and get)

Inherited from:
Environment
def addStepDef(name: String, stepDef: Scenario): Scenario

Adds a step definition to the context.

Adds a step definition to the context.

Value parameters:
name

the name

stepDef

the step definition to add

Inherited from:
Environment
def addStepDef(stepDef: Scenario): Scenario

Adds a step definition to the context.

Adds a step definition to the context.

Value parameters:
stepDef

the step definition to add

Inherited from:
Environment
def addVideo(videoFile: File): Unit
Inherited from:
Environment
def asString: String
Inherited from:
Environment
def checkSimilarity(value1: String, value2: String, operator: SimilarityOperator, percentage: Double, negate: Boolean): Try[(Boolean, Option[Double])]
Inherited from:
EvalContext
def cloneState: EnvState

Create a clone of the current environment state

Create a clone of the current environment state

Inherited from:
Environment
def compare(sourceName: String, expected: String, actual: String, operator: ComparisonOperator, negate: Boolean): Try[Boolean]
Inherited from:
EvalContext
def currentBehavior: Option[BehaviorType]

Gets the current behavior.

Gets the current behavior.

Inherited from:
Environment
def decodeBase64(source: String): String

Decodes a base 64 encoded string.

Decodes a base 64 encoded string.

Value parameters:
source

the encoded source string

Returns:

the decoded result string

Inherited from:
DecodingSupport
def dscSimilarity(value1: String, value2: String): Option[Double]

Compares two strings for similarity and returns a percentage score.

Compares two strings for similarity and returns a percentage score.

Value parameters:
value1

string 1

value2

string 2

Returns:

the DSC similarity score (if it could be calculated), otherwise None

Inherited from:
SimilaritySupport
def evaluate[U](dryValue: => U)(function: => U): U

Evaluates an function or returns the given dry value depending on--dry-run mode.

Evaluates an function or returns the given dry value depending on--dry-run mode.

Value parameters:
dryValue

the dry value

function

the function to evaluate

Inherited from:
EvalContext
def evaluateJSPredicate(javascript: String, params: Any*): Boolean

Evaluates a javascript predicate.

Evaluates a javascript predicate.

Value parameters:
javascript

the script predicate expression to execute (must evaluate to true or false)

params

optional parameters to the script

Inherited from:
ScriptSupport
def evaluateJsonPath(jsonpath: String, source: String): String

Evaluates an json path expression against a JSON source string and returns the result.

Evaluates an json path expression against a JSON source string and returns the result.

Value parameters:
jsonpath

the json path expression

source

the json source string

Returns:

the result of evaluating the json path expression

Inherited from:
JsonPathSupport
def evaluateXPath(xpath: String, source: String, targetType: XMLNodeType): String

Evaluates an xpath expression against an xml source string and returns the result.

Evaluates an xpath expression against an xml source string and returns the result.

Value parameters:
source

the xml source string

targetType

the target node type

xpath

the expath expression

Returns:

the result of evaluating the xpath expression

Throws:
gwen.Errors.XPathException

if the xpath expression fails to evaluate

Inherited from:
XPathSupport
def executeSQLQuery(sql: String, database: String): String

Evaluates an SQL query against a database and returns the first column value of the first row in the result.

Evaluates an SQL query against a database and returns the first column value of the first row in the result.

Value parameters:
database

the database name

sql

the SQL statement to execute

Returns:

the first column value of the first row in the result

Inherited from:
SQLSupport
def executeSQLUpdate(sql: String, database: String): Int

Executes an SQL update statement against a database and returns the number of rows affected.

Executes an SQL update statement against a database and returns the number of rows affected.

Value parameters:
database

the database name

sql

the SQL update statement to execute

Returns:

the number of rows affected (as a string)

Inherited from:
SQLSupport
def extractByRegex(regex: String, source: String): String

Extracts a substring from a source string by regex. The value in the first matching regex group is returned, otherwise an error is thrown.

Extracts a substring from a source string by regex. The value in the first matching regex group is returned, otherwise an error is thrown.

Value parameters:
regex

the regex extractor pattern

source

the source string

Returns:

the extracted value

Throws:
gwen.Errors.RegexException

if the regex fails to evaluate

Inherited from:
RegexSupport
def filterAtts(pred: (String, String) => Boolean): ScopedDataStack

Filters all attributes in all scopes based on the given predicate.

Filters all attributes in all scopes based on the given predicate.

Value parameters:
pred

the predicate filter to apply; a (name, value) => boolean function

Returns:

a new Scoped data stack containing only the attributes accepted by the predicate;

Inherited from:
Environment
def getBinding(name: String): Binding[EvalContext, String]

Gets a named binding

Gets a named binding

Value parameters:
name

the binding name

Returns:

a binding

Inherited from:
EvalContext
def getStepDef(expression: String, docString: Option[String]): Option[Scenario]

Gets the paraterised step definition for the given expression.

Gets the paraterised step definition for the given expression.

Value parameters:
docString

optional step docString (parameter)

expression

the step expression to get the step definition for

Returns:

the step definition and its parameters (name value tuples) if a match is found; None otherwise

Inherited from:
Environment
def getVideos: List[File]
Inherited from:
Environment
def interpolate(step: Step): Step

Interpolate all references in the given step.

Interpolate all references in the given step.

Value parameters:
step

the step to interpolate

Returns:

the interpolated step

Inherited from:
EvalContext
def interpolate(value: String): String
Inherited from:
EvalContext
def interpolateParams(step: Step): Step

Interpolate all parameters in the given step before it is evaluated.

Interpolate all parameters in the given step before it is evaluated.

Value parameters:
step

the step to interpolate

Returns:

the interpolated step

Inherited from:
EvalContext
final def interpolateParams(source: String)(resolve: String => String): String
Inherited from:
Interpolator
final def interpolateString(source: String)(resolve: String => String): String
Inherited from:
Interpolator
def isEvaluatingTopLevelStep: Boolean

Checks if a top level step is currently being evaluated).

Checks if a top level step is currently being evaluated).

Inherited from:
Environment
def matchTemplate(template: String, source: String, sourceName: String, topScope: TopScope): Try[Boolean]

Matches a template against a given source and extracts, ignores, or injects values.

Matches a template against a given source and extracts, ignores, or injects values.

Value parameters:
source

the source string

sourceName

the name of the source attribute

template

the template string

Returns:

success if there is a match; an error otherwise

Inherited from:
TemplateSupport
def nodeChain: NodeChain
Inherited from:
Environment
def paramScope: ParameterStack
Inherited from:
Environment
def parseExpression(operator: ComparisonOperator, expression: String): String
Inherited from:
EvalContext
def perform(operation: => Unit): Option[Any]

Performs an operation only if --dry-run mode is off.

Performs an operation only if --dry-run mode is off.

Value parameters:
operation

the operation to execute

Inherited from:
EvalContext
def popAttachments(): List[(Int, String, File)]
Inherited from:
Environment
def popBehavior(): Option[BehaviorType]

Removes the current behavior.

Removes the current behavior.

Inherited from:
Environment
def popNode(): (GwenNode, NodeChain)

Pops a node off the node chain.

Pops a node off the node chain.

Inherited from:
Environment
def pushNode(node: GwenNode): NodeChain

Pushes a node onto the node chain.

Pushes a node onto the node chain.

Inherited from:
Environment
def removeStepDef(name: String): Scenario

Removes (unloads) the stepdef with the given name

Removes (unloads) the stepdef with the given name

Value parameters:
name

the step def name

Returns:

the removed step def

Inherited from:
Environment
def scopes: ScopedDataStack
Inherited from:
Environment
def sessionClosed(event: WebSessionEvent): Unit
def specType: SpecType

The spec type currently being evaluated.

The spec type currently being evaluated.

Inherited from:
Environment
def stateLevel: StateLevel
Inherited from:
Environment
def stepDefs: Map[String, Scenario]
Inherited from:
Environment
def topScope: TopScope
Inherited from:
Environment
def visibleScopes: ScopedDataStack

Returns the current visible scopes.

Returns the current visible scopes.

Inherited from:
Environment
def withStep(step: Step)(stepFunction: Step => Step): Step

Applies a function to a step and captures the result.

Applies a function to a step and captures the result.

Value parameters:
step

the step to evaluate

stepFunction

the step evaluator function

Inherited from:
EvalContext

Inherited fields

@transient
lazy protected val logger: Logger
Inherited from:
LazyLogging