Class ExecuteJavaScript

Namespace

CSF.Screenplay.Selenium.Actions

Assembly

CSF.Screenplay.Selenium.dll

An action which sends a JavaScript string to a web browser and executes it. This action ignores the result (if any) from that script.

public class ExecuteJavaScript : IPerformable, ICanReport

Inheritance

object

ExecuteJavaScript

Implements

IPerformable

ICanReport

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

In this example, the script will write "I can count to 5" into the developer console.

using static CSF.Screenplay.Selenium.PerformableBuilder;

var iCanCount = new NamedScript<int>("console.log('I can count to ' + arguments[0])", "my counting script");

// Within the logic of a custom task, deriving from IPerformable
public async ValueTask PerformAsAsync(ICanPerform actor, CancellationToken cancellationToken = default)
{
    // ... other performance logic
    await actor.PerformAsync(ExecuteAScript(iCanCount, 5), cancellationToken);
    // ... other performance logic
}

Remarks

The best way to use this action is via the builder method ExecuteAScript(NamedScript) or one of its same-named overloads. The NamedScript class, and its counterparts with generic type parameters, provide a manner in which scripts to be executed by this action may be stored within the application or test logic, providing type safety for their parameters.

Performing this action, as an actor which has the BrowseTheWeb ability, sends the body of the script and its parameter values to the web browser and executes it. This is roughly equivalent to a user opening the developer tools Console, typing the script and its parameters there, and pressing enter. This action does not return any result from the script, so it is useful only when the script to execute does not return a result, or when the intent is to ignore the result. If the result is important then use ExecuteJavaScriptAndGetResult<TResult> instead.

Within the script body, any parameters are accessible via the arguments object. That object exposes the parameter values by their zero-based index (position) in the parameters list. So, a script which takes three parameters will expose these to the script as arguments[0], arguments[1] and arguments[2], respectively for the first, second and third parameter values.

Constructors

ExecuteJavaScript(string, string, params object[])

Initialises a new instance of ExecuteJavaScript.

public ExecuteJavaScript(string script, string scriptName, params object[] arguments)

Parameters

script string

The JavaScript to be executed.

scriptName string

A human-readable name for the script, which may be displayed in a Screenplay report.

arguments object[]

A collection of arguments/parameters to the script.

Exceptions

ArgumentException

If either script or scriptName are null or whitespace-only.

Methods

GetReportFragment(Actor, IFormatsReportFragment)

Gets a fragment of a Screenplay report, specific to the execution (performables) or gaining (abilities) of the current instance, for the specified actor.

public ReportFragment GetReportFragment(Actor actor, IFormatsReportFragment formatter)

Parameters

actor Actor

An actor for whom to write the report fragment

formatter IFormatsReportFragment

A report-formatting service

Returns

ReportFragment

A human-readable report fragment.

Examples

For a performable which clicks a button (where the button itself has been constructor-injected into the performable instance), then a suitable return value might be a formatted string such as {Actor name} clicks {Button}, where the two placeholders indicated by braces: {} are substituted with the actor's Name and a string representation of the button.

For a performable which reads the temperature from a thermometer, a suitable return value might be a string in the format {Actor name} reads the temperature.

For an ability which allows the actor to wash dishes then a suitable return value might be a string in the format {Actor name} is able to wash the dishes.

Remarks

Implementers should return a string which indicates that the named actor is performing (present tense) the performable, for types which also implement a performable interface. For types which represent abilities, the implementer should return a string which indicates that the named actor is able to do something. In particular for abilities, to make them easily recognisable in reports, it helps to stick to the convention {Actor name} is able to {Ability summary}.

For performables which return a value (Questions, or Tasks which behave like Questions), there is no need to include the returned value within the report fragment. The framework will include the return value in the report and will format it via a different mechanism.

Good report fragments are concise. Be aware that report fragments for Tasks (which are composed from other performables) do not need to go into detail about what they do. Users reading Screenplay reports are able to drill-down into Tasks to see what they are composed from, so if the user is curious as to what the task does, it is easy to discover. It is also strongly recommended to avoid periods (full stops) at the end of a report fragment. Whilst report fragments tend to be complete sentences, punctuation like this is distracting and reports are seldom presented as paragraphs of prose.

PerformAsAsync(ICanPerform, CancellationToken)

Performs the action(s) are represented by the current instance.

public ValueTask PerformAsAsync(ICanPerform actor, CancellationToken cancellationToken = default)

Parameters

actor ICanPerform

The actor that is performing.

cancellationToken CancellationToken

An optional cancellation token by which to abort the performable.

Returns

ValueTask

A task which completes when the performable represented by the current instance is complete.

See Also

ExecuteAScript(NamedScript)

ExecuteAScript<T1>(NamedScript<T1>, T1)

ExecuteAScript<T1, T2>(NamedScript<T1, T2>, T1, T2)

ExecuteAScript<T1, T2, T3>(NamedScript<T1, T2, T3>, T1, T2, T3)

ExecuteAScript<T1, T2, T3, T4>(NamedScript<T1, T2, T3, T4>, T1, T2, T3, T4)

ExecuteAScript<T1, T2, T3, T4, T5>(NamedScript<T1, T2, T3, T4, T5>, T1, T2, T3, T4, T5)

ExecuteAScript<T1, T2, T3, T4, T5, T6>(NamedScript<T1, T2, T3, T4, T5, T6>, T1, T2, T3, T4, T5, T6)

ExecuteAScript<T1, T2, T3, T4, T5, T6, T7>(NamedScript<T1, T2, T3, T4, T5, T6, T7>, T1, T2, T3, T4, T5, T6, T7)

ExecuteJavaScriptAndGetResult<TResult>