chromedp/cdp/runtime/runtime.go

// Package runtime provides the Chrome Debugging Protocol
// commands, types, and events for the Runtime domain.
//
// 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.
//
// Generated by the chromedp-gen command.
package runtime

// Code generated by chromedp-gen. DO NOT EDIT.

import (
	"context"

	cdp "github.com/knq/chromedp/cdp"
)

// EvaluateParams evaluates expression on global object.
type EvaluateParams struct {
	Expression            string             `json:"expression"`                      // Expression to evaluate.
	ObjectGroup           string             `json:"objectGroup,omitempty"`           // Symbolic group name that can be used to release multiple objects.
	IncludeCommandLineAPI bool               `json:"includeCommandLineAPI,omitempty"` // Determines whether Command Line API should be available during the evaluation.
	Silent                bool               `json:"silent,omitempty"`                // In silent mode exceptions thrown during evaluation are not reported and do not pause execution. Overrides setPauseOnException state.
	ContextID             ExecutionContextID `json:"contextId,omitempty"`             // 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.
	ReturnByValue         bool               `json:"returnByValue,omitempty"`         // Whether the result is expected to be a JSON object that should be sent by value.
	GeneratePreview       bool               `json:"generatePreview,omitempty"`       // Whether preview should be generated for the result.
	UserGesture           bool               `json:"userGesture,omitempty"`           // Whether execution should be treated as initiated by user in the UI.
	AwaitPromise          bool               `json:"awaitPromise,omitempty"`          // Whether execution should await for resulting value and return once awaited promise is resolved.
}

// Evaluate evaluates expression on global object.
//
// parameters:
//   expression - Expression to evaluate.
func Evaluate(expression string) *EvaluateParams {
	return &EvaluateParams{
		Expression: expression,
	}
}

// WithObjectGroup symbolic group name that can be used to release multiple
// objects.
func (p EvaluateParams) WithObjectGroup(objectGroup string) *EvaluateParams {
	p.ObjectGroup = objectGroup
	return &p
}

// WithIncludeCommandLineAPI determines whether Command Line API should be
// available during the evaluation.
func (p EvaluateParams) WithIncludeCommandLineAPI(includeCommandLineAPI bool) *EvaluateParams {
	p.IncludeCommandLineAPI = includeCommandLineAPI
	return &p
}

// WithSilent in silent mode exceptions thrown during evaluation are not
// reported and do not pause execution. Overrides setPauseOnException state.
func (p EvaluateParams) WithSilent(silent bool) *EvaluateParams {
	p.Silent = silent
	return &p
}

// WithContextID 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.
func (p EvaluateParams) WithContextID(contextID ExecutionContextID) *EvaluateParams {
	p.ContextID = contextID
	return &p
}

// WithReturnByValue whether the result is expected to be a JSON object that
// should be sent by value.
func (p EvaluateParams) WithReturnByValue(returnByValue bool) *EvaluateParams {
	p.ReturnByValue = returnByValue
	return &p
}

// WithGeneratePreview whether preview should be generated for the result.
func (p EvaluateParams) WithGeneratePreview(generatePreview bool) *EvaluateParams {
	p.GeneratePreview = generatePreview
	return &p
}

// WithUserGesture whether execution should be treated as initiated by user
// in the UI.
func (p EvaluateParams) WithUserGesture(userGesture bool) *EvaluateParams {
	p.UserGesture = userGesture
	return &p
}

// WithAwaitPromise whether execution should await for resulting value and
// return once awaited promise is resolved.
func (p EvaluateParams) WithAwaitPromise(awaitPromise bool) *EvaluateParams {
	p.AwaitPromise = awaitPromise
	return &p
}

// EvaluateReturns return values.
type EvaluateReturns struct {
	Result           *RemoteObject     `json:"result,omitempty"`           // Evaluation result.
	ExceptionDetails *ExceptionDetails `json:"exceptionDetails,omitempty"` // Exception details.
}

// Do executes Runtime.evaluate against the provided context and
// target handler.
//
// returns:
//   result - Evaluation result.
//   exceptionDetails - Exception details.
func (p *EvaluateParams) Do(ctxt context.Context, h cdp.Handler) (result *RemoteObject, exceptionDetails *ExceptionDetails, err error) {
	// execute
	var res EvaluateReturns
	err = h.Execute(ctxt, cdp.CommandRuntimeEvaluate, p, &res)
	if err != nil {
		return nil, nil, err
	}

	return res.Result, res.ExceptionDetails, nil
}

// AwaitPromiseParams add handler to promise with given promise object id.
type AwaitPromiseParams struct {
	PromiseObjectID RemoteObjectID `json:"promiseObjectId"`           // Identifier of the promise.
	ReturnByValue   bool           `json:"returnByValue,omitempty"`   // Whether the result is expected to be a JSON object that should be sent by value.
	GeneratePreview bool           `json:"generatePreview,omitempty"` // Whether preview should be generated for the result.
}

// AwaitPromise add handler to promise with given promise object id.
//
// parameters:
//   promiseObjectID - Identifier of the promise.
func AwaitPromise(promiseObjectID RemoteObjectID) *AwaitPromiseParams {
	return &AwaitPromiseParams{
		PromiseObjectID: promiseObjectID,
	}
}

// WithReturnByValue whether the result is expected to be a JSON object that
// should be sent by value.
func (p AwaitPromiseParams) WithReturnByValue(returnByValue bool) *AwaitPromiseParams {
	p.ReturnByValue = returnByValue
	return &p
}

// WithGeneratePreview whether preview should be generated for the result.
func (p AwaitPromiseParams) WithGeneratePreview(generatePreview bool) *AwaitPromiseParams {
	p.GeneratePreview = generatePreview
	return &p
}

// AwaitPromiseReturns return values.
type AwaitPromiseReturns struct {
	Result           *RemoteObject     `json:"result,omitempty"`           // Promise result. Will contain rejected value if promise was rejected.
	ExceptionDetails *ExceptionDetails `json:"exceptionDetails,omitempty"` // Exception details if stack strace is available.
}

// Do executes Runtime.awaitPromise against the provided context and
// target handler.
//
// returns:
//   result - Promise result. Will contain rejected value if promise was rejected.
//   exceptionDetails - Exception details if stack strace is available.
func (p *AwaitPromiseParams) Do(ctxt context.Context, h cdp.Handler) (result *RemoteObject, exceptionDetails *ExceptionDetails, err error) {
	// execute
	var res AwaitPromiseReturns
	err = h.Execute(ctxt, cdp.CommandRuntimeAwaitPromise, p, &res)
	if err != nil {
		return nil, nil, err
	}

	return res.Result, res.ExceptionDetails, nil
}

// CallFunctionOnParams calls function with given declaration on the given
// object. Object group of the result is inherited from the target object.
type CallFunctionOnParams struct {
	ObjectID            RemoteObjectID  `json:"objectId"`                  // Identifier of the object to call function on.
	FunctionDeclaration string          `json:"functionDeclaration"`       // Declaration of the function to call.
	Arguments           []*CallArgument `json:"arguments,omitempty"`       // Call arguments. All call arguments must belong to the same JavaScript world as the target object.
	Silent              bool            `json:"silent,omitempty"`          // In silent mode exceptions thrown during evaluation are not reported and do not pause execution. Overrides setPauseOnException state.
	ReturnByValue       bool            `json:"returnByValue,omitempty"`   // Whether the result is expected to be a JSON object which should be sent by value.
	GeneratePreview     bool            `json:"generatePreview,omitempty"` // Whether preview should be generated for the result.
	UserGesture         bool            `json:"userGesture,omitempty"`     // Whether execution should be treated as initiated by user in the UI.
	AwaitPromise        bool            `json:"awaitPromise,omitempty"`    // Whether execution should await for resulting value and return once awaited promise is resolved.
}

// CallFunctionOn calls function with given declaration on the given object.
// Object group of the result is inherited from the target object.
//
// parameters:
//   objectID - Identifier of the object to call function on.
//   functionDeclaration - Declaration of the function to call.
func CallFunctionOn(objectID RemoteObjectID, functionDeclaration string) *CallFunctionOnParams {
	return &CallFunctionOnParams{
		ObjectID:            objectID,
		FunctionDeclaration: functionDeclaration,
	}
}

// WithArguments call arguments. All call arguments must belong to the same
// JavaScript world as the target object.
func (p CallFunctionOnParams) WithArguments(arguments []*CallArgument) *CallFunctionOnParams {
	p.Arguments = arguments
	return &p
}

// WithSilent in silent mode exceptions thrown during evaluation are not
// reported and do not pause execution. Overrides setPauseOnException state.
func (p CallFunctionOnParams) WithSilent(silent bool) *CallFunctionOnParams {
	p.Silent = silent
	return &p
}

// WithReturnByValue whether the result is expected to be a JSON object which
// should be sent by value.
func (p CallFunctionOnParams) WithReturnByValue(returnByValue bool) *CallFunctionOnParams {
	p.ReturnByValue = returnByValue
	return &p
}

// WithGeneratePreview whether preview should be generated for the result.
func (p CallFunctionOnParams) WithGeneratePreview(generatePreview bool) *CallFunctionOnParams {
	p.GeneratePreview = generatePreview
	return &p
}

// WithUserGesture whether execution should be treated as initiated by user
// in the UI.
func (p CallFunctionOnParams) WithUserGesture(userGesture bool) *CallFunctionOnParams {
	p.UserGesture = userGesture
	return &p
}

// WithAwaitPromise whether execution should await for resulting value and
// return once awaited promise is resolved.
func (p CallFunctionOnParams) WithAwaitPromise(awaitPromise bool) *CallFunctionOnParams {
	p.AwaitPromise = awaitPromise
	return &p
}

// CallFunctionOnReturns return values.
type CallFunctionOnReturns struct {
	Result           *RemoteObject     `json:"result,omitempty"`           // Call result.
	ExceptionDetails *ExceptionDetails `json:"exceptionDetails,omitempty"` // Exception details.
}

// Do executes Runtime.callFunctionOn against the provided context and
// target handler.
//
// returns:
//   result - Call result.
//   exceptionDetails - Exception details.
func (p *CallFunctionOnParams) Do(ctxt context.Context, h cdp.Handler) (result *RemoteObject, exceptionDetails *ExceptionDetails, err error) {
	// execute
	var res CallFunctionOnReturns
	err = h.Execute(ctxt, cdp.CommandRuntimeCallFunctionOn, p, &res)
	if err != nil {
		return nil, nil, err
	}

	return res.Result, res.ExceptionDetails, nil
}

// GetPropertiesParams returns properties of a given object. Object group of
// the result is inherited from the target object.
type GetPropertiesParams struct {
	ObjectID               RemoteObjectID `json:"objectId"`                         // Identifier of the object to return properties for.
	OwnProperties          bool           `json:"ownProperties,omitempty"`          // If true, returns properties belonging only to the element itself, not to its prototype chain.
	AccessorPropertiesOnly bool           `json:"accessorPropertiesOnly,omitempty"` // If true, returns accessor properties (with getter/setter) only; internal properties are not returned either.
	GeneratePreview        bool           `json:"generatePreview,omitempty"`        // Whether preview should be generated for the results.
}

// GetProperties returns properties of a given object. Object group of the
// result is inherited from the target object.
//
// parameters:
//   objectID - Identifier of the object to return properties for.
func GetProperties(objectID RemoteObjectID) *GetPropertiesParams {
	return &GetPropertiesParams{
		ObjectID: objectID,
	}
}

// WithOwnProperties if true, returns properties belonging only to the
// element itself, not to its prototype chain.
func (p GetPropertiesParams) WithOwnProperties(ownProperties bool) *GetPropertiesParams {
	p.OwnProperties = ownProperties
	return &p
}

// WithAccessorPropertiesOnly if true, returns accessor properties (with
// getter/setter) only; internal properties are not returned either.
func (p GetPropertiesParams) WithAccessorPropertiesOnly(accessorPropertiesOnly bool) *GetPropertiesParams {
	p.AccessorPropertiesOnly = accessorPropertiesOnly
	return &p
}

// WithGeneratePreview whether preview should be generated for the results.
func (p GetPropertiesParams) WithGeneratePreview(generatePreview bool) *GetPropertiesParams {
	p.GeneratePreview = generatePreview
	return &p
}

// GetPropertiesReturns return values.
type GetPropertiesReturns struct {
	Result             []*PropertyDescriptor         `json:"result,omitempty"`             // Object properties.
	InternalProperties []*InternalPropertyDescriptor `json:"internalProperties,omitempty"` // Internal object properties (only of the element itself).
	ExceptionDetails   *ExceptionDetails             `json:"exceptionDetails,omitempty"`   // Exception details.
}

// Do executes Runtime.getProperties against the provided context and
// target handler.
//
// returns:
//   result - Object properties.
//   internalProperties - Internal object properties (only of the element itself).
//   exceptionDetails - Exception details.
func (p *GetPropertiesParams) Do(ctxt context.Context, h cdp.Handler) (result []*PropertyDescriptor, internalProperties []*InternalPropertyDescriptor, exceptionDetails *ExceptionDetails, err error) {
	// execute
	var res GetPropertiesReturns
	err = h.Execute(ctxt, cdp.CommandRuntimeGetProperties, p, &res)
	if err != nil {
		return nil, nil, nil, err
	}

	return res.Result, res.InternalProperties, res.ExceptionDetails, nil
}

// ReleaseObjectParams releases remote object with given id.
type ReleaseObjectParams struct {
	ObjectID RemoteObjectID `json:"objectId"` // Identifier of the object to release.
}

// ReleaseObject releases remote object with given id.
//
// parameters:
//   objectID - Identifier of the object to release.
func ReleaseObject(objectID RemoteObjectID) *ReleaseObjectParams {
	return &ReleaseObjectParams{
		ObjectID: objectID,
	}
}

// Do executes Runtime.releaseObject against the provided context and
// target handler.
func (p *ReleaseObjectParams) Do(ctxt context.Context, h cdp.Handler) (err error) {
	return h.Execute(ctxt, cdp.CommandRuntimeReleaseObject, p, nil)
}

// ReleaseObjectGroupParams releases all remote objects that belong to a
// given group.
type ReleaseObjectGroupParams struct {
	ObjectGroup string `json:"objectGroup"` // Symbolic object group name.
}

// ReleaseObjectGroup releases all remote objects that belong to a given
// group.
//
// parameters:
//   objectGroup - Symbolic object group name.
func ReleaseObjectGroup(objectGroup string) *ReleaseObjectGroupParams {
	return &ReleaseObjectGroupParams{
		ObjectGroup: objectGroup,
	}
}

// Do executes Runtime.releaseObjectGroup against the provided context and
// target handler.
func (p *ReleaseObjectGroupParams) Do(ctxt context.Context, h cdp.Handler) (err error) {
	return h.Execute(ctxt, cdp.CommandRuntimeReleaseObjectGroup, p, nil)
}

// RunIfWaitingForDebuggerParams tells inspected instance to run if it was
// waiting for debugger to attach.
type RunIfWaitingForDebuggerParams struct{}

// RunIfWaitingForDebugger tells inspected instance to run if it was waiting
// for debugger to attach.
func RunIfWaitingForDebugger() *RunIfWaitingForDebuggerParams {
	return &RunIfWaitingForDebuggerParams{}
}

// Do executes Runtime.runIfWaitingForDebugger against the provided context and
// target handler.
func (p *RunIfWaitingForDebuggerParams) Do(ctxt context.Context, h cdp.Handler) (err error) {
	return h.Execute(ctxt, cdp.CommandRuntimeRunIfWaitingForDebugger, nil, nil)
}

// EnableParams 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.
type EnableParams struct{}

// Enable 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.
func Enable() *EnableParams {
	return &EnableParams{}
}

// Do executes Runtime.enable against the provided context and
// target handler.
func (p *EnableParams) Do(ctxt context.Context, h cdp.Handler) (err error) {
	return h.Execute(ctxt, cdp.CommandRuntimeEnable, nil, nil)
}

// DisableParams disables reporting of execution contexts creation.
type DisableParams struct{}

// Disable disables reporting of execution contexts creation.
func Disable() *DisableParams {
	return &DisableParams{}
}

// Do executes Runtime.disable against the provided context and
// target handler.
func (p *DisableParams) Do(ctxt context.Context, h cdp.Handler) (err error) {
	return h.Execute(ctxt, cdp.CommandRuntimeDisable, nil, nil)
}

// DiscardConsoleEntriesParams discards collected exceptions and console API
// calls.
type DiscardConsoleEntriesParams struct{}

// DiscardConsoleEntries discards collected exceptions and console API calls.
func DiscardConsoleEntries() *DiscardConsoleEntriesParams {
	return &DiscardConsoleEntriesParams{}
}

// Do executes Runtime.discardConsoleEntries against the provided context and
// target handler.
func (p *DiscardConsoleEntriesParams) Do(ctxt context.Context, h cdp.Handler) (err error) {
	return h.Execute(ctxt, cdp.CommandRuntimeDiscardConsoleEntries, nil, nil)
}

// SetCustomObjectFormatterEnabledParams [no description].
type SetCustomObjectFormatterEnabledParams struct {
	Enabled bool `json:"enabled"`
}

// SetCustomObjectFormatterEnabled [no description].
//
// parameters:
//   enabled
func SetCustomObjectFormatterEnabled(enabled bool) *SetCustomObjectFormatterEnabledParams {
	return &SetCustomObjectFormatterEnabledParams{
		Enabled: enabled,
	}
}

// Do executes Runtime.setCustomObjectFormatterEnabled against the provided context and
// target handler.
func (p *SetCustomObjectFormatterEnabledParams) Do(ctxt context.Context, h cdp.Handler) (err error) {
	return h.Execute(ctxt, cdp.CommandRuntimeSetCustomObjectFormatterEnabled, p, nil)
}

// CompileScriptParams compiles expression.
type CompileScriptParams struct {
	Expression         string             `json:"expression"`                   // Expression to compile.
	SourceURL          string             `json:"sourceURL"`                    // Source url to be set for the script.
	PersistScript      bool               `json:"persistScript"`                // Specifies whether the compiled script should be persisted.
	ExecutionContextID ExecutionContextID `json:"executionContextId,omitempty"` // 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.
}

// CompileScript compiles expression.
//
// parameters:
//   expression - Expression to compile.
//   sourceURL - Source url to be set for the script.
//   persistScript - Specifies whether the compiled script should be persisted.
func CompileScript(expression string, sourceURL string, persistScript bool) *CompileScriptParams {
	return &CompileScriptParams{
		Expression:    expression,
		SourceURL:     sourceURL,
		PersistScript: persistScript,
	}
}

// WithExecutionContextID 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.
func (p CompileScriptParams) WithExecutionContextID(executionContextID ExecutionContextID) *CompileScriptParams {
	p.ExecutionContextID = executionContextID
	return &p
}

// CompileScriptReturns return values.
type CompileScriptReturns struct {
	ScriptID         ScriptID          `json:"scriptId,omitempty"`         // Id of the script.
	ExceptionDetails *ExceptionDetails `json:"exceptionDetails,omitempty"` // Exception details.
}

// Do executes Runtime.compileScript against the provided context and
// target handler.
//
// returns:
//   scriptID - Id of the script.
//   exceptionDetails - Exception details.
func (p *CompileScriptParams) Do(ctxt context.Context, h cdp.Handler) (scriptID ScriptID, exceptionDetails *ExceptionDetails, err error) {
	// execute
	var res CompileScriptReturns
	err = h.Execute(ctxt, cdp.CommandRuntimeCompileScript, p, &res)
	if err != nil {
		return "", nil, err
	}

	return res.ScriptID, res.ExceptionDetails, nil
}

// RunScriptParams runs script with given id in a given context.
type RunScriptParams struct {
	ScriptID              ScriptID           `json:"scriptId"`                        // Id of the script to run.
	ExecutionContextID    ExecutionContextID `json:"executionContextId,omitempty"`    // 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.
	ObjectGroup           string             `json:"objectGroup,omitempty"`           // Symbolic group name that can be used to release multiple objects.
	Silent                bool               `json:"silent,omitempty"`                // In silent mode exceptions thrown during evaluation are not reported and do not pause execution. Overrides setPauseOnException state.
	IncludeCommandLineAPI bool               `json:"includeCommandLineAPI,omitempty"` // Determines whether Command Line API should be available during the evaluation.
	ReturnByValue         bool               `json:"returnByValue,omitempty"`         // Whether the result is expected to be a JSON object which should be sent by value.
	GeneratePreview       bool               `json:"generatePreview,omitempty"`       // Whether preview should be generated for the result.
	AwaitPromise          bool               `json:"awaitPromise,omitempty"`          // Whether execution should await for resulting value and return once awaited promise is resolved.
}

// RunScript runs script with given id in a given context.
//
// parameters:
//   scriptID - Id of the script to run.
func RunScript(scriptID ScriptID) *RunScriptParams {
	return &RunScriptParams{
		ScriptID: scriptID,
	}
}

// WithExecutionContextID 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.
func (p RunScriptParams) WithExecutionContextID(executionContextID ExecutionContextID) *RunScriptParams {
	p.ExecutionContextID = executionContextID
	return &p
}

// WithObjectGroup symbolic group name that can be used to release multiple
// objects.
func (p RunScriptParams) WithObjectGroup(objectGroup string) *RunScriptParams {
	p.ObjectGroup = objectGroup
	return &p
}

// WithSilent in silent mode exceptions thrown during evaluation are not
// reported and do not pause execution. Overrides setPauseOnException state.
func (p RunScriptParams) WithSilent(silent bool) *RunScriptParams {
	p.Silent = silent
	return &p
}

// WithIncludeCommandLineAPI determines whether Command Line API should be
// available during the evaluation.
func (p RunScriptParams) WithIncludeCommandLineAPI(includeCommandLineAPI bool) *RunScriptParams {
	p.IncludeCommandLineAPI = includeCommandLineAPI
	return &p
}

// WithReturnByValue whether the result is expected to be a JSON object which
// should be sent by value.
func (p RunScriptParams) WithReturnByValue(returnByValue bool) *RunScriptParams {
	p.ReturnByValue = returnByValue
	return &p
}

// WithGeneratePreview whether preview should be generated for the result.
func (p RunScriptParams) WithGeneratePreview(generatePreview bool) *RunScriptParams {
	p.GeneratePreview = generatePreview
	return &p
}

// WithAwaitPromise whether execution should await for resulting value and
// return once awaited promise is resolved.
func (p RunScriptParams) WithAwaitPromise(awaitPromise bool) *RunScriptParams {
	p.AwaitPromise = awaitPromise
	return &p
}

// RunScriptReturns return values.
type RunScriptReturns struct {
	Result           *RemoteObject     `json:"result,omitempty"`           // Run result.
	ExceptionDetails *ExceptionDetails `json:"exceptionDetails,omitempty"` // Exception details.
}

// Do executes Runtime.runScript against the provided context and
// target handler.
//
// returns:
//   result - Run result.
//   exceptionDetails - Exception details.
func (p *RunScriptParams) Do(ctxt context.Context, h cdp.Handler) (result *RemoteObject, exceptionDetails *ExceptionDetails, err error) {
	// execute
	var res RunScriptReturns
	err = h.Execute(ctxt, cdp.CommandRuntimeRunScript, p, &res)
	if err != nil {
		return nil, nil, err
	}

	return res.Result, res.ExceptionDetails, nil
}