README
About chrome-protocol
A relatively thin wrapper on top of code that is generated based on the chrome devtool protocol. Aims to provide a few of the basic commands that one would desire when automating actions in chrome or any other browser that supports the protocol.
This is still a work in progress.
- Very fast.
- No hidden errors.
- No hidden sleep calls/timeouts.
- Simple approach makes it easy to understand what is happening under the hood.
Examples
Look under github.com/4ydx/chrome-protocol/actions. The testing files are the examples. There is one example in the example folder.
- Click
- Fill
- Focus
- Navigation
- Screenshot
- As well as other actions (css style retrieval, javascript evaluation, etc).
I will be working on other actions as I need them for my own personal projects.
You can take the generated code in github.com/4ydx/cdp and create your own higher level actions for interacting with the browser. This will require understanding the Devtools Reference.
Navigation example:
package main
import (
"github.com/4ydx/chrome-protocol"
"github.com/4ydx/chrome-protocol/actions"
"log"
"time"
)
func main() {
browser := cdp.NewBrowser("/usr/bin/google-chrome", 9222, "browser.log")
frame := cdp.Start(browser, cdp.LogBasic)
defer func() {
// passing false prevents the browser from stopping immediately
frame.Stop(false)
// Give yourself time to view the final page in the browser.
time.Sleep(3 * time.Second)
browser.Stop()
}()
// Enable page events
if err := actions.EnablePage(frame, time.Second*2); err != nil {
panic(err)
}
// Navigate
if _, err := actions.Navigate(frame, "https://google.com", time.Second*5); err != nil {
panic(err)
}
log.Printf("\n-- All completed for %s --\n", frame.FrameID)
}
Creating your own Actions
Actions encapsulate everything you need in order to interact with a browser. An action contains commands and events.
When you construct an action, you need to fill in at least one command that consists of the struct representing the parameters that will be sent with the command, the struct that represents the reply to that command from the server, and the method name of the API call you are making.
It is possible to associate events that the server will send to the client with your action. By specifying events you can be sure that a given action has actually run its course and the browser state is where you would expect it to be.
API methods, command parameters, command responses, possible events, and types are all defined in the Devtools Reference.
This is a possible Navigation action that watches for the FrameStoppedLoadingReply event which helps to ensure that navigation to a url is fully completed.
// Navigate sends the browser to the given URL
func Navigate(frame *cdp.Frame, url string, timeout time.Duration) ([]cdp.Event, error) {
events := GetNavigationEvents()
action := cdp.NewAction(frame,
events,
[]cdp.Command{
cdp.Command{ID: frame.RequestID.GetNext(), Method: page.CommandPageNavigate, Params: &page.NavigateArgs{URL: url}, Reply: &page.NavigateReply{}, Timeout: timeout},
})
if err := action.Run(); err != nil {
log.Print(err)
return events, err
}
return events, nil
}
Caveats
- Concurrent actions are currently not supported.
Documentation
Index ¶
- Constants
- Variables
- func GetWebsocket(lg *log.Logger, port int) *websocket.Conn
- func Read(frame *Frame)
- func SendClose(lg *log.Logger, c *websocket.Conn)
- func UpdateDOMEvent(frame *Frame, method string, event json.Unmarshaler)
- func Write(frame *Frame)
- type Action
- type Browser
- type Command
- type CommandReply
- type Error
- type Event
- type Frame
- func (f *Frame) AddDOMNode(node dom.Node)
- func (f *Frame) Children(parentID dom.NodeID) []dom.Node
- func (f *Frame) Clear()
- func (f *Frame) CommandTimeout() <-chan time.Time
- func (f *Frame) FindByAttribute(parentID dom.NodeID, attribute, value string) []dom.Node
- func (f *Frame) GetCommandMethod() string
- func (f *Frame) GetDOM() *dom.GetFlattenedDocumentReply
- func (f *Frame) GetFrameID() string
- func (f *Frame) HasCommandID(id int64) bool
- func (f *Frame) HasEvent(name string) bool
- func (f *Frame) IsCommandComplete() bool
- func (f *Frame) IsComplete() bool
- func (f *Frame) Log()
- func (f *Frame) SetCurrentAction(act *Action)
- func (f *Frame) SetDOM(dom *dom.GetFlattenedDocumentReply)
- func (f *Frame) SetEvent(frame *Frame, name string, m Message) error
- func (f *Frame) SetResult(frame *Frame, m Message) error
- func (f *Frame) Stop(closeBrowser bool)
- func (f *Frame) ToJSON() []byte
- type LogLevelValue
- type Message
- type RequestID
Constants ¶
const ( // LogBasic records outgoing commands, their replies, and any specified events. LogBasic = LogLevelValue(0) // LogDetails records additional details about the reply from the server for a given command/event. LogDetails = LogLevelValue(1) // LogAll records everything. LogAll = LogLevelValue(2) )
Variables ¶
var Wait = time.Millisecond * 50
Wait is the default timeout taken as the action wait loop runs. The loop's select is triggered and the action will be checked for completion.
Functions ¶
func GetWebsocket ¶
GetWebsocket returns a websocket connection to the running browser.
func UpdateDOMEvent ¶
func UpdateDOMEvent(frame *Frame, method string, event json.Unmarshaler)
UpdateDOMEvent takes the event and, for a certain subset of events, makes sure that the current DOM object is updated.
Types ¶
type Action ¶
Action represents a collection of json requests (commands) and any events that those requests might trigger that need to be tracked.
type Browser ¶
type Browser struct { Port int PID int TempDir string LogFile *os.File Log *log.Logger ConsoleFile *os.File Console *log.Logger }
Browser contains information required to stop an exec'd browser at a later point in time.
func NewBrowser ¶
NewBrowser accepts the path to the browser's binary, the port, and any arguments that need to be passed to the binary.
type Command ¶
type Command struct { // Values required to make a chrome devtools protocol request. ID int64 `json:"id"` Method string `json:"method,omitempty"` Params json.Marshaler `json:"params,omitempty"` Reply CommandReply `json:"-"` // The struct that will be filled when a matching command Id is found in a reply over the chrome websocket. Timeout time.Duration `json:"-"` // How long until the current command experiences a timeout, which will halt the entire process. }
Command represents a single json request sent to the server over the websocket.
type CommandReply ¶
type CommandReply interface { json.Unmarshaler MatchFrameID(frameID string, m []byte) (bool, error) GetFrameID() string }
CommandReply specifies required methods for handling the json encoded replies received from the server.
type Error ¶
type Error struct { Code int64 `json:"code"` // Error code. Message string `json:"message"` // Error message. }
Error error type that is apart of the Message struct.
type Event ¶
type Event struct { Name string Value CommandReply IsRequired bool IsFound bool }
Event holds the value returned by the server based on a matching MethodType name.
type Frame ¶
type Frame struct { *sync.RWMutex DOM *dom.GetFlattenedDocumentReply FrameID string LoaderID string RequestID RequestID Browser *Browser // Conn is the connection to the websocket. Conn *websocket.Conn // AllComplete will trigger a close on the websocket. // Typically AllComplete or the OsInterrupt channels will fire and the write loop will send a request to close the socket. AllComplete chan struct{} // CacheCompleteChan sends the signal that the cached action is completed (all commands and events). CacheCompleteChan chan struct{} // CommandChan sends the signal that a command has been completed and an Action can advance. CommandChan chan (<-chan time.Time) // ActionChan sends Actions to the websocket. ActionChan chan []byte // CurrentAction stores the Action that is currently active. CurrentAction *Action // LogLevel specifies how much information should be f.Browser.Logged. Higher number results in more data. LogLevel LogLevelValue }
Frame stores the current FrameID.
func Start ¶
func Start(browser *Browser, logLevel LogLevelValue) *Frame
Start prepares required resources to begin automation.
func (*Frame) AddDOMNode ¶
AddDOMNode allows for setting the Frame DOM value safely.
func (*Frame) Children ¶
Children returns a deep copy of the child nodes of the given parentID. NOTE: Expecting that code elsewhere has already populated the frame.DOM object.
func (*Frame) CommandTimeout ¶
CommandTimeout once timed out will trigger an error and stop the automation.
func (*Frame) FindByAttribute ¶
FindByAttribute will search the existing cached DOM for nodes whose given attribute matches the given value starting at the root specified by nodeID. NOTE: Expecting that code elsewhere has already populated the frame.DOM object.
func (*Frame) GetCommandMethod ¶
GetCommandMethod returns the method of the command that is currently active or the very last method.
func (*Frame) GetDOM ¶
func (f *Frame) GetDOM() *dom.GetFlattenedDocumentReply
GetDOM allows for getting the Frame DOM value safely. This could be a bit racy depending on when documentUpdated events are fired.
func (*Frame) GetFrameID ¶
GetFrameID returns the current frameID.
func (*Frame) HasCommandID ¶
HasCommandID determines if an id matches the current action's command's unique id.
func (*Frame) HasEvent ¶
HasEvent returns true when the action has an event with the given MethodType.
func (*Frame) IsCommandComplete ¶
IsCommandComplete indicates that all commands are complete.
func (*Frame) IsComplete ¶
IsComplete indicates that all commands and events are complete.
func (*Frame) Log ¶
func (f *Frame) Log()
Log writes the current state of the action to the f.Browser.Log.
func (*Frame) SetCurrentAction ¶
SetCurrentAction sets the current action that the frame is evaluating.
func (*Frame) SetDOM ¶
func (f *Frame) SetDOM(dom *dom.GetFlattenedDocumentReply)
SetDOM allows for setting the Frame DOM value safely.
type Message ¶
type Message struct { ID int64 `json:"id,omitempty"` // Unique message identifier. Method string `json:"method,omitempty"` // Event or command type. Params json.RawMessage `json:"params,omitempty"` // Event or command parameters. Result json.RawMessage `json:"result,omitempty"` // Command return values. Error *Error `json:"error,omitempty"` // Error message. }
Message is the chrome DevTools Protocol message sent/read over the websocket connection.
Directories
Path | Synopsis |
---|---|
actions | |
example/runtime |