Class ExecuteJavaScriptAndGetResult<TResult>
- Namespace
- CSF.Screenplay.Selenium.Questions
- Assembly
- CSF.Screenplay.Selenium.dll
A question which executes some arbitrary JavaScript in the web browser and returns the result returned by that script.
public class ExecuteJavaScriptAndGetResult<TResult> : IPerformableWithResult<TResult>, ICanReportType Parameters
TResultThe expected type of the result from the script
- Inheritance
-
ExecuteJavaScriptAndGetResult<TResult>
- Implements
-
IPerformableWithResult<TResult>
- Inherited Members
Examples
In this example, the script will return the integer value 10 to the performance.
using static CSF.Screenplay.Selenium.PerformableBuilder;
var addFour = new NamedScriptWithResult<int, int>("4 + arguments[0]", "add four");
// Within the logic of a custom task, deriving from IPerformableWithResult<int>
public async ValueTask<int> PerformAsAsync(ICanPerform actor, CancellationToken cancellationToken = default)
{
return await actor.PerformAsync(ExecuteAScript(addFour, 6), cancellationToken);
}Remarks
The best way to use this action is via the builder method ExecuteAScript<TResult>(NamedScriptWithResult<TResult>) or one of its same-named overloads. The NamedScriptWithResult<TResult> class, and its counterparts with additional 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 and return value.
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, then reading the result which is returned by the console. This action returns the from the script back to the IPerformance. If the result is unimportant or you wish to execute a script which does not return a result then use ExecuteJavaScript 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
ExecuteJavaScriptAndGetResult(string, string, params object[])
Initialises a new instance of ExecuteJavaScriptAndGetResult<TResult>.
public ExecuteJavaScriptAndGetResult(string script, string scriptName, params object[] arguments)Parameters
scriptstringThe JavaScript to be executed.
scriptNamestringA human-readable name for the script, which may be displayed in a Screenplay report.
argumentsobject[]A collection of arguments/parameters to the script.
Exceptions
- ArgumentException
If either
scriptorscriptNameare 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
actorActorAn actor for whom to write the report fragment
formatterIFormatsReportFragmentA 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 and returns a strongly-typed value.
public ValueTask<TResult> PerformAsAsync(ICanPerform actor, CancellationToken cancellationToken = default)Parameters
actorICanPerformThe actor that is performing.
cancellationTokenCancellationTokenAn optional cancellation token by which to abort the performable.
Returns
- ValueTask<TResult>
A task which exposes a strongly-typed 'result' value when the performable represented by the current instance is complete.