com.github.testsmith.cdt.protocol.commands.Runtime Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of cdt-java-client Show documentation
Show all versions of cdt-java-client Show documentation
Chrome DevTools java client
The newest version!
package com.github.testsmith.cdt.protocol.commands;
/*-
* #%L
* cdt-java-client
* %%
* Copyright (C) 2018 - 2024 Kenan Klisura
* %%
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
* #L%
*/
import com.github.testsmith.cdt.protocol.events.runtime.BindingCalled;
import com.github.testsmith.cdt.protocol.events.runtime.ConsoleAPICalled;
import com.github.testsmith.cdt.protocol.events.runtime.ExceptionRevoked;
import com.github.testsmith.cdt.protocol.events.runtime.ExceptionThrown;
import com.github.testsmith.cdt.protocol.events.runtime.ExecutionContextCreated;
import com.github.testsmith.cdt.protocol.events.runtime.ExecutionContextDestroyed;
import com.github.testsmith.cdt.protocol.events.runtime.ExecutionContextsCleared;
import com.github.testsmith.cdt.protocol.events.runtime.InspectRequested;
import com.github.testsmith.cdt.protocol.support.annotations.EventName;
import com.github.testsmith.cdt.protocol.support.annotations.Experimental;
import com.github.testsmith.cdt.protocol.support.annotations.Optional;
import com.github.testsmith.cdt.protocol.support.annotations.ParamName;
import com.github.testsmith.cdt.protocol.support.annotations.ReturnTypeParameter;
import com.github.testsmith.cdt.protocol.support.annotations.Returns;
import com.github.testsmith.cdt.protocol.support.types.EventHandler;
import com.github.testsmith.cdt.protocol.support.types.EventListener;
import com.github.testsmith.cdt.protocol.types.runtime.AwaitPromise;
import com.github.testsmith.cdt.protocol.types.runtime.CallArgument;
import com.github.testsmith.cdt.protocol.types.runtime.CallFunctionOn;
import com.github.testsmith.cdt.protocol.types.runtime.CompileScript;
import com.github.testsmith.cdt.protocol.types.runtime.Evaluate;
import com.github.testsmith.cdt.protocol.types.runtime.HeapUsage;
import com.github.testsmith.cdt.protocol.types.runtime.Properties;
import com.github.testsmith.cdt.protocol.types.runtime.RemoteObject;
import com.github.testsmith.cdt.protocol.types.runtime.RunScript;
import java.util.List;
/**
* Runtime domain exposes JavaScript runtime by means of remote evaluation and mirror objects.
* Evaluation results are returned as mirror object that expose object type, string representation
* and unique identifier that can be used for further object reference. Original objects are
* maintained in memory unless they are either explicitly released or are released along with the
* other objects in their object group.
*
* @author roy
* @version $Id: $Id
*/
public interface Runtime {
/**
* Add handler to promise with given promise object id.
*
* @param promiseObjectId Identifier of the promise.
* @return a {@link com.github.testsmith.cdt.protocol.types.runtime.AwaitPromise} object
*/
AwaitPromise awaitPromise(@ParamName("promiseObjectId") String promiseObjectId);
/**
* Add handler to promise with given promise object id.
*
* @param promiseObjectId Identifier of the promise.
* @param returnByValue Whether the result is expected to be a JSON object that should be sent by
* value.
* @param generatePreview Whether preview should be generated for the result.
* @return a {@link com.github.testsmith.cdt.protocol.types.runtime.AwaitPromise} object
*/
AwaitPromise awaitPromise(
@ParamName("promiseObjectId") String promiseObjectId,
@Optional @ParamName("returnByValue") Boolean returnByValue,
@Optional @ParamName("generatePreview") Boolean generatePreview);
/**
* Calls function with given declaration on the given object. Object group of the result is
* inherited from the target object.
*
* @param functionDeclaration Declaration of the function to call.
* @return a {@link com.github.testsmith.cdt.protocol.types.runtime.CallFunctionOn} object
*/
CallFunctionOn callFunctionOn(@ParamName("functionDeclaration") String functionDeclaration);
/**
* Calls function with given declaration on the given object. Object group of the result is
* inherited from the target object.
*
* @param functionDeclaration Declaration of the function to call.
* @param objectId Identifier of the object to call function on. Either objectId or
* executionContextId should be specified.
* @param arguments Call arguments. All call arguments must belong to the same JavaScript world as
* the target object.
* @param silent In silent mode exceptions thrown during evaluation are not reported and do not
* pause execution. Overrides `setPauseOnException` state.
* @param returnByValue Whether the result is expected to be a JSON object which should be sent by
* value.
* @param generatePreview Whether preview should be generated for the result.
* @param userGesture Whether execution should be treated as initiated by user in the UI.
* @param awaitPromise Whether execution should `await` for resulting value and return once
* awaited promise is resolved.
* @param executionContextId Specifies execution context which global object will be used to call
* function on. Either executionContextId or objectId should be specified.
* @param objectGroup Symbolic group name that can be used to release multiple objects. If
* objectGroup is not specified and objectId is, objectGroup will be inherited from object.
* @return a {@link com.github.testsmith.cdt.protocol.types.runtime.CallFunctionOn} object
*/
CallFunctionOn callFunctionOn(
@ParamName("functionDeclaration") String functionDeclaration,
@Optional @ParamName("objectId") String objectId,
@Optional @ParamName("arguments") List arguments,
@Optional @ParamName("silent") Boolean silent,
@Optional @ParamName("returnByValue") Boolean returnByValue,
@Experimental @Optional @ParamName("generatePreview") Boolean generatePreview,
@Optional @ParamName("userGesture") Boolean userGesture,
@Optional @ParamName("awaitPromise") Boolean awaitPromise,
@Optional @ParamName("executionContextId") Integer executionContextId,
@Optional @ParamName("objectGroup") String objectGroup);
/**
* Compiles expression.
*
* @param expression Expression to compile.
* @param sourceURL Source url to be set for the script.
* @param persistScript Specifies whether the compiled script should be persisted.
* @return a {@link com.github.testsmith.cdt.protocol.types.runtime.CompileScript} object
*/
CompileScript compileScript(
@ParamName("expression") String expression,
@ParamName("sourceURL") String sourceURL,
@ParamName("persistScript") Boolean persistScript);
/**
* Compiles expression.
*
* @param expression Expression to compile.
* @param sourceURL Source url to be set for the script.
* @param persistScript Specifies whether the compiled script should be persisted.
* @param executionContextId Specifies in which execution context to perform script run. If the
* parameter is omitted the evaluation will be performed in the context of the inspected page.
* @return a {@link com.github.testsmith.cdt.protocol.types.runtime.CompileScript} object
*/
CompileScript compileScript(
@ParamName("expression") String expression,
@ParamName("sourceURL") String sourceURL,
@ParamName("persistScript") Boolean persistScript,
@Optional @ParamName("executionContextId") Integer executionContextId);
/** Disables reporting of execution contexts creation. */
void disable();
/** Discards collected exceptions and console API calls. */
void discardConsoleEntries();
/**
* Enables reporting of execution contexts creation by means of `executionContextCreated` event.
* When the reporting gets enabled the event will be sent immediately for each existing execution
* context.
*/
void enable();
/**
* Evaluates expression on global object.
*
* @param expression Expression to evaluate.
* @return a {@link com.github.testsmith.cdt.protocol.types.runtime.Evaluate} object
*/
Evaluate evaluate(@ParamName("expression") String expression);
/**
* Evaluates expression on global object.
*
* @param expression Expression to evaluate.
* @param objectGroup Symbolic group name that can be used to release multiple objects.
* @param includeCommandLineAPI Determines whether Command Line API should be available during the
* evaluation.
* @param silent In silent mode exceptions thrown during evaluation are not reported and do not
* pause execution. Overrides `setPauseOnException` state.
* @param contextId Specifies in which execution context to perform evaluation. If the parameter
* is omitted the evaluation will be performed in the context of the inspected page. This is
* mutually exclusive with `uniqueContextId`, which offers an alternative way to identify the
* execution context that is more reliable in a multi-process environment.
* @param returnByValue Whether the result is expected to be a JSON object that should be sent by
* value.
* @param generatePreview Whether preview should be generated for the result.
* @param userGesture Whether execution should be treated as initiated by user in the UI.
* @param awaitPromise Whether execution should `await` for resulting value and return once
* awaited promise is resolved.
* @param throwOnSideEffect Whether to throw an exception if side effect cannot be ruled out
* during evaluation. This implies `disableBreaks` below.
* @param timeout Terminate execution after timing out (number of milliseconds).
* @param disableBreaks Disable breakpoints during execution.
* @param replMode Setting this flag to true enables `let` re-declaration and top-level `await`.
* Note that `let` variables can only be re-declared if they originate from `replMode`
* themselves.
* @param allowUnsafeEvalBlockedByCSP The Content Security Policy (CSP) for the target might block
* 'unsafe-eval' which includes eval(), Function(), setTimeout() and setInterval() when called
* with non-callable arguments. This flag bypasses CSP for this evaluation and allows
* unsafe-eval. Defaults to true.
* @param uniqueContextId An alternative way to specify the execution context to evaluate in.
* Compared to contextId that may be reused accross processes, this is guaranteed to be
* system-unique, so it can be used to prevent accidental evaluation of the expression in
* context different than intended (e.g. as a result of navigation accross process
* boundaries). This is mutually exclusive with `contextId`.
* @return a {@link com.github.testsmith.cdt.protocol.types.runtime.Evaluate} object
*/
Evaluate evaluate(
@ParamName("expression") String expression,
@Optional @ParamName("objectGroup") String objectGroup,
@Optional @ParamName("includeCommandLineAPI") Boolean includeCommandLineAPI,
@Optional @ParamName("silent") Boolean silent,
@Optional @ParamName("contextId") Integer contextId,
@Optional @ParamName("returnByValue") Boolean returnByValue,
@Experimental @Optional @ParamName("generatePreview") Boolean generatePreview,
@Optional @ParamName("userGesture") Boolean userGesture,
@Optional @ParamName("awaitPromise") Boolean awaitPromise,
@Experimental @Optional @ParamName("throwOnSideEffect") Boolean throwOnSideEffect,
@Experimental @Optional @ParamName("timeout") Double timeout,
@Experimental @Optional @ParamName("disableBreaks") Boolean disableBreaks,
@Experimental @Optional @ParamName("replMode") Boolean replMode,
@Experimental @Optional @ParamName("allowUnsafeEvalBlockedByCSP")
Boolean allowUnsafeEvalBlockedByCSP,
@Experimental @Optional @ParamName("uniqueContextId") String uniqueContextId);
/**
* Returns the isolate id.
*
* @return a {@link java.lang.String} object
*/
@Experimental
@Returns("id")
String getIsolateId();
/**
* Returns the JavaScript heap usage. It is the total usage of the corresponding isolate not
* scoped to a particular Runtime.
*
* @return a {@link com.github.testsmith.cdt.protocol.types.runtime.HeapUsage} object
*/
@Experimental
HeapUsage getHeapUsage();
/**
* Returns properties of a given object. Object group of the result is inherited from the target
* object.
*
* @param objectId Identifier of the object to return properties for.
* @return a {@link com.github.testsmith.cdt.protocol.types.runtime.Properties} object
*/
Properties getProperties(@ParamName("objectId") String objectId);
/**
* Returns properties of a given object. Object group of the result is inherited from the target
* object.
*
* @param objectId Identifier of the object to return properties for.
* @param ownProperties If true, returns properties belonging only to the element itself, not to
* its prototype chain.
* @param accessorPropertiesOnly If true, returns accessor properties (with getter/setter) only;
* internal properties are not returned either.
* @param generatePreview Whether preview should be generated for the results.
* @return a {@link com.github.testsmith.cdt.protocol.types.runtime.Properties} object
*/
Properties getProperties(
@ParamName("objectId") String objectId,
@Optional @ParamName("ownProperties") Boolean ownProperties,
@Experimental @Optional @ParamName("accessorPropertiesOnly") Boolean accessorPropertiesOnly,
@Experimental @Optional @ParamName("generatePreview") Boolean generatePreview);
/**
* Returns all let, const and class variables from global scope.
*
* @return a {@link java.util.List} object
*/
@Returns("names")
@ReturnTypeParameter(String.class)
List globalLexicalScopeNames();
/**
* Returns all let, const and class variables from global scope.
*
* @param executionContextId Specifies in which execution context to lookup global scope
* variables.
* @return a {@link java.util.List} object
*/
@Returns("names")
@ReturnTypeParameter(String.class)
List globalLexicalScopeNames(
@Optional @ParamName("executionContextId") Integer executionContextId);
/** @param prototypeObjectId Identifier of the prototype to return objects for. */
/**
* queryObjects.
*
* @param prototypeObjectId a {@link java.lang.String} object
* @return a {@link com.github.testsmith.cdt.protocol.types.runtime.RemoteObject} object
*/
@Returns("objects")
RemoteObject queryObjects(@ParamName("prototypeObjectId") String prototypeObjectId);
/**
* queryObjects.
*
* @param prototypeObjectId Identifier of the prototype to return objects for.
* @param objectGroup Symbolic group name that can be used to release the results.
* @return a {@link com.github.testsmith.cdt.protocol.types.runtime.RemoteObject} object
*/
@Returns("objects")
RemoteObject queryObjects(
@ParamName("prototypeObjectId") String prototypeObjectId,
@Optional @ParamName("objectGroup") String objectGroup);
/**
* Releases remote object with given id.
*
* @param objectId Identifier of the object to release.
*/
void releaseObject(@ParamName("objectId") String objectId);
/**
* Releases all remote objects that belong to a given group.
*
* @param objectGroup Symbolic object group name.
*/
void releaseObjectGroup(@ParamName("objectGroup") String objectGroup);
/** Tells inspected instance to run if it was waiting for debugger to attach. */
void runIfWaitingForDebugger();
/**
* Runs script with given id in a given context.
*
* @param scriptId Id of the script to run.
* @return a {@link com.github.testsmith.cdt.protocol.types.runtime.RunScript} object
*/
RunScript runScript(@ParamName("scriptId") String scriptId);
/**
* Runs script with given id in a given context.
*
* @param scriptId Id of the script to run.
* @param executionContextId Specifies in which execution context to perform script run. If the
* parameter is omitted the evaluation will be performed in the context of the inspected page.
* @param objectGroup Symbolic group name that can be used to release multiple objects.
* @param silent In silent mode exceptions thrown during evaluation are not reported and do not
* pause execution. Overrides `setPauseOnException` state.
* @param includeCommandLineAPI Determines whether Command Line API should be available during the
* evaluation.
* @param returnByValue Whether the result is expected to be a JSON object which should be sent by
* value.
* @param generatePreview Whether preview should be generated for the result.
* @param awaitPromise Whether execution should `await` for resulting value and return once
* awaited promise is resolved.
* @return a {@link com.github.testsmith.cdt.protocol.types.runtime.RunScript} object
*/
RunScript runScript(
@ParamName("scriptId") String scriptId,
@Optional @ParamName("executionContextId") Integer executionContextId,
@Optional @ParamName("objectGroup") String objectGroup,
@Optional @ParamName("silent") Boolean silent,
@Optional @ParamName("includeCommandLineAPI") Boolean includeCommandLineAPI,
@Optional @ParamName("returnByValue") Boolean returnByValue,
@Optional @ParamName("generatePreview") Boolean generatePreview,
@Optional @ParamName("awaitPromise") Boolean awaitPromise);
/** @param enabled */
/**
* setCustomObjectFormatterEnabled.
*
* @param enabled a {@link java.lang.Boolean} object
*/
@Experimental
void setCustomObjectFormatterEnabled(@ParamName("enabled") Boolean enabled);
/** @param size */
/**
* setMaxCallStackSizeToCapture.
*
* @param size a {@link java.lang.Integer} object
*/
@Experimental
void setMaxCallStackSizeToCapture(@ParamName("size") Integer size);
/**
* Terminate current or next JavaScript execution. Will cancel the termination when the outer-most
* script execution ends.
*/
@Experimental
void terminateExecution();
/**
* If executionContextId is empty, adds binding with the given name on the global objects of all
* inspected contexts, including those created later, bindings survive reloads. Binding function
* takes exactly one argument, this argument should be string, in case of any other input,
* function throws an exception. Each binding function call produces Runtime.bindingCalled
* notification.
*
* @param name a {@link java.lang.String} object
*/
@Experimental
void addBinding(@ParamName("name") String name);
/**
* If executionContextId is empty, adds binding with the given name on the global objects of all
* inspected contexts, including those created later, bindings survive reloads. Binding function
* takes exactly one argument, this argument should be string, in case of any other input,
* function throws an exception. Each binding function call produces Runtime.bindingCalled
* notification.
*
* @param name a {@link java.lang.String} object
* @param executionContextId If specified, the binding would only be exposed to the specified
* execution context. If omitted and `executionContextName` is not set, the binding is exposed
* to all execution contexts of the target. This parameter is mutually exclusive with
* `executionContextName`.
* @param executionContextName If specified, the binding is exposed to the executionContext with
* matching name, even for contexts created after the binding is added. See also
* `ExecutionContext.name` and `worldName` parameter to
* `Page.addScriptToEvaluateOnNewDocument`. This parameter is mutually exclusive with
* `executionContextId`.
*/
@Experimental
void addBinding(
@ParamName("name") String name,
@Optional @ParamName("executionContextId") Integer executionContextId,
@Experimental @Optional @ParamName("executionContextName") String executionContextName);
/**
* This method does not remove binding function from global object but unsubscribes current
* runtime agent from Runtime.bindingCalled notifications.
*
* @param name a {@link java.lang.String} object
*/
@Experimental
void removeBinding(@ParamName("name") String name);
/**
* Notification is issued every time when binding is called.
*
* @param eventListener a {@link com.github.testsmith.cdt.protocol.support.types.EventHandler}
* object
* @return a {@link com.github.testsmith.cdt.protocol.support.types.EventListener} object
*/
@EventName("bindingCalled")
@Experimental
EventListener onBindingCalled(EventHandler eventListener);
/**
* Issued when console API was called.
*
* @param eventListener a {@link com.github.testsmith.cdt.protocol.support.types.EventHandler}
* object
* @return a {@link com.github.testsmith.cdt.protocol.support.types.EventListener} object
*/
@EventName("consoleAPICalled")
EventListener onConsoleAPICalled(EventHandler eventListener);
/**
* Issued when unhandled exception was revoked.
*
* @param eventListener a {@link com.github.testsmith.cdt.protocol.support.types.EventHandler}
* object
* @return a {@link com.github.testsmith.cdt.protocol.support.types.EventListener} object
*/
@EventName("exceptionRevoked")
EventListener onExceptionRevoked(EventHandler eventListener);
/**
* Issued when exception was thrown and unhandled.
*
* @param eventListener a {@link com.github.testsmith.cdt.protocol.support.types.EventHandler}
* object
* @return a {@link com.github.testsmith.cdt.protocol.support.types.EventListener} object
*/
@EventName("exceptionThrown")
EventListener onExceptionThrown(EventHandler eventListener);
/**
* Issued when new execution context is created.
*
* @param eventListener a {@link com.github.testsmith.cdt.protocol.support.types.EventHandler}
* object
* @return a {@link com.github.testsmith.cdt.protocol.support.types.EventListener} object
*/
@EventName("executionContextCreated")
EventListener onExecutionContextCreated(EventHandler eventListener);
/**
* Issued when execution context is destroyed.
*
* @param eventListener a {@link com.github.testsmith.cdt.protocol.support.types.EventHandler}
* object
* @return a {@link com.github.testsmith.cdt.protocol.support.types.EventListener} object
*/
@EventName("executionContextDestroyed")
EventListener onExecutionContextDestroyed(EventHandler eventListener);
/**
* Issued when all executionContexts were cleared in browser
*
* @param eventListener a {@link com.github.testsmith.cdt.protocol.support.types.EventHandler}
* object
* @return a {@link com.github.testsmith.cdt.protocol.support.types.EventListener} object
*/
@EventName("executionContextsCleared")
EventListener onExecutionContextsCleared(EventHandler eventListener);
/**
* Issued when object should be inspected (for example, as a result of inspect() command line API
* call).
*
* @param eventListener a {@link com.github.testsmith.cdt.protocol.support.types.EventHandler}
* object
* @return a {@link com.github.testsmith.cdt.protocol.support.types.EventListener} object
*/
@EventName("inspectRequested")
EventListener onInspectRequested(EventHandler eventListener);
}