chromebot

README

Chromebot

Package chromebot provides a high-level interface to automate tasks in Chrome or Chromium. Work based on chromedp.

Installation

go get -v github.com/nanitefactory/chromebot

Test

go test -v github.com/nanitefactory/chromebot

Quick start

// Start a browser
browser := chromebot.New(false)
defer browser.Close()

// Navigate
browser.Tab(0).Run(
    chromedp.Navigate("https://godoc.org"),
    chromedp.WaitVisible("html"),
)

// Another navigation method
// browser.Tab(0).Do().Page().Navigate("https://godoc.org", nil, nil, nil)

// Get cookies
cookies, err := browser.Tab(0).Do().Network().GetAllCookies()
if err != nil {
    panic(err)
}

// Print
for i, cookie := range cookies {
    fmt.Println(i, cookie)
}

// _Output:
// 0 &{__utma 58978491.1884756898.1576137201.1576137201.1576137201.1 .godoc.org / 1.639209201e+09 60 false false false }
// 1 &{__utmc 58978491 .godoc.org / -1 14 false false true }
// 2 &{__utmz 58978491.1576137201.1.1.utmcsr=(direct)|utmccn=(direct)|utmcmd=(none) .godoc.org / 1.591905201e+09 75 false false false }
// 3 &{__utmt 1 .godoc.org / 1.576137801e+09 7 false false false }
// 4 &{__utmb 58978491.1.10.1576137201 .godoc.org / 1.576139001e+09 30 false false false }

Documentation

Overview

Package chromebot simplifies driving browsers based on chromedp.

Index

• Variables
• type Builder
  • func NewBuilder() *Builder
  • func (b *Builder) NewChrome() *Chrome
  • func (b *Builder) WithBrowserOption(opts ...chromedp.BrowserOption) *Builder
  • func (b *Builder) WithContextOption(opts ...chromedp.ContextOption) *Builder
  • func (b *Builder) WithDeadline(d time.Time) *Builder
  • func (b *Builder) WithExecAllocatorOption(opts ...chromedp.ExecAllocatorOption) *Builder
  • func (b *Builder) WithFlags(arg BuilderFlags) *Builder
• type BuilderFlags
• type Chrome
  • func New(headless bool) *Chrome
  • func NewChrome(headless bool) *Chrome
  • func (c *Chrome) AddNewTab(opts ...chromedp.ContextOption) (added *Tab)
  • func (c *Chrome) Close()
  • func (c *Chrome) CountTabs() int
  • func (c *Chrome) Dead() <-chan struct{}
  • func (c *Chrome) Listen(onBrowserEvent func(ev interface{})) error
  • func (c *Chrome) Tab(indexOfTab int) *Tab
• type Tab
  • func (t *Tab) Close()
  • func (t *Tab) Dead() <-chan struct{}
  • func (t *Tab) Do() domain.Domain
  • func (t *Tab) Listen(onEvent func(ev interface{})) error
  • func (t *Tab) Run(actions ...chromedp.Action) error

Examples

• New

Variables

var DefaultBuilderFlags = BuilderFlags{
	NoFirstRun:            true,
	NoDefaultBrowserCheck: true,
	Headless:              true,
	HideScrollbars:        true,
	MuteAudio:             true,

	UserDataDir: "",
	ProxyServer: "",
	WindowSize: struct {
		Width  int
		Height int
	}{-1, -1},
	UserAgent:  "",
	NoSandbox:  false,
	DisableGPU: false,

	DisableBackgroundNetworking:         true,
	EnableFeatures:                      "NetworkService,NetworkServiceInProcess",
	DisableBackgroundTimerThrottling:    true,
	DisableBackgroundingOccludedWindows: true,
	DisableBreakpad:                     true,
	DisableClientSidePhishingDetection:  true,
	DisableDefaultApps:                  true,
	DisableDevShmUsage:                  true,
	DisableExtensions:                   true,
	DisableFeatures:                     "site-per-process,TranslateUI,BlinkGenPropertyTrees",
	DisableHangMonitor:                  true,
	DisableIpcFloodingProtection:        true,
	DisablePopupBlocking:                true,
	DisablePromptOnRepost:               true,
	DisableRendererBackgrounding:        true,
	DisableSync:                         true,
	ForceColorProfile:                   "srgb",
	MetricsRecordingOnly:                true,
	SafebrowsingDisableAutoUpdate:       true,
	EnableAutomation:                    true,
	PasswordStore:                       "basic",
	UseMockKeychain:                     true,
}

DefaultBuilderFlags is a set of generic command line options to pass as flags to Chrome.

Types

type Builder

type Builder struct {
	// contains filtered or unexported fields
}

Builder builds a Chrome instance.

func NewBuilder

func NewBuilder() *Builder

NewBuilder is a constructor.

func (*Builder) NewChrome

func (b *Builder) NewChrome() *Chrome

NewChrome creates a Chrome instance.

func (*Builder) WithBrowserOption

func (b *Builder) WithBrowserOption(opts ...chromedp.BrowserOption) *Builder

WithBrowserOption sets options. Generally unused.

func (*Builder) WithContextOption

func (b *Builder) WithContextOption(opts ...chromedp.ContextOption) *Builder

WithContextOption sets options. Generally unused.

func (*Builder) WithDeadline

func (b *Builder) WithDeadline(d time.Time) *Builder

WithDeadline sets the deadline. Generally unused.

func (*Builder) WithExecAllocatorOption

func (b *Builder) WithExecAllocatorOption(opts ...chromedp.ExecAllocatorOption) *Builder

WithExecAllocatorOption sets options. Generally unused.

func (*Builder) WithFlags

func (b *Builder) WithFlags(arg BuilderFlags) *Builder

WithFlags sets a set of generic command line options to pass as flags to Chrome. Recommend use with `DefaultFlags`.

type BuilderFlags

type BuilderFlags struct {
	NoFirstRun            bool
	NoDefaultBrowserCheck bool
	Headless              bool
	HideScrollbars        bool
	MuteAudio             bool
	//
	UserDataDir string // UserDataDir is the command line option to set the profile directory used by Chrome.
	ProxyServer string // ProxyServer is the command line option to set the outbound proxy server.
	WindowSize  struct {
		Width  int
		Height int
	}
	UserAgent  string
	NoSandbox  bool
	DisableGPU bool
	//
	DisableBackgroundNetworking         bool
	EnableFeatures                      string
	DisableBackgroundTimerThrottling    bool
	DisableBackgroundingOccludedWindows bool
	DisableBreakpad                     bool
	DisableClientSidePhishingDetection  bool
	DisableDefaultApps                  bool
	DisableDevShmUsage                  bool
	DisableExtensions                   bool
	DisableFeatures                     string
	DisableHangMonitor                  bool
	DisableIpcFloodingProtection        bool
	DisablePopupBlocking                bool
	DisablePromptOnRepost               bool
	DisableRendererBackgrounding        bool
	DisableSync                         bool
	ForceColorProfile                   string
	MetricsRecordingOnly                bool
	SafebrowsingDisableAutoUpdate       bool
	EnableAutomation                    bool
	PasswordStore                       string
	UseMockKeychain                     bool
}

BuilderFlags is a set of generic command line options to pass as flags to Chrome.

type Chrome

type Chrome struct {
	// contains filtered or unexported fields
}

Chrome represents a running Chrome browser.

func New

func New(headless bool) *Chrome

New is an alias for NewChrome.

Example

package main

import (
	"fmt"

	"github.com/chromedp/chromedp"
	"github.com/nanitefactory/chromebot"
)

func main() {
	// Start a browser
	browser := chromebot.New(false)
	defer browser.Close()

	// Navigate
	browser.Tab(0).Run(
		chromedp.Navigate("https://godoc.org"),
		chromedp.WaitVisible("html"),
	)

	// Another navigation method
	// browser.Tab(0).Do().Page().Navigate("https://godoc.org", nil, nil, nil)

	// Get cookies
	cookies, err := browser.Tab(0).Do().Network().GetAllCookies()
	if err != nil {
		panic(err)
	}

	// Print
	for i, cookie := range cookies {
		fmt.Println(i, cookie)
	}

	// _Output:
	// 0 &{__utma 58978491.1884756898.1576137201.1576137201.1576137201.1 .godoc.org / 1.639209201e+09 60 false false false }
	// 1 &{__utmc 58978491 .godoc.org / -1 14 false false true }
	// 2 &{__utmz 58978491.1576137201.1.1.utmcsr=(direct)|utmccn=(direct)|utmcmd=(none) .godoc.org / 1.591905201e+09 75 false false false }
	// 3 &{__utmt 1 .godoc.org / 1.576137801e+09 7 false false false }
	// 4 &{__utmb 58978491.1.10.1576137201 .godoc.org / 1.576139001e+09 30 false false false }
}

func NewChrome

func NewChrome(headless bool) *Chrome

NewChrome runs a new browser. Use `(*Chrome).Close()` to free the browser allocated by this.

func (*Chrome) AddNewTab

func (c *Chrome) AddNewTab(opts ...chromedp.ContextOption) (added *Tab)

AddNewTab creates a new tab and add it to this Chrome. The function returns `nil` when the browser is dead. Panic if `chromedp.WithBrowserOption()` passed as an argument. Only tab options are accepted.

func (*Chrome) Close

func (c *Chrome) Close()

Close gracefully closes the browser and all its tabs.

func (*Chrome) CountTabs

func (c *Chrome) CountTabs() int

CountTabs returns the number of tabs created by this Chrome.

func (*Chrome) Dead

func (c *Chrome) Dead() <-chan struct{}

Dead returns a channel that's closed when work done on behalf of the browser should be dead. This notifies a user when this browser is closed.

func (*Chrome) Listen

func (c *Chrome) Listen(onBrowserEvent func(ev interface{})) error

Listen adds a callback function which will be called whenever a browser event is received on this browser.

Usage:

c.Listen(func(ev interface{}) {
	switch ev := ev.(type) {
	case *runtime.EventConsoleAPICalled:
		// do something with ev
	case *runtime.EventExceptionThrown:
		// do something with ev
	}
})

Note that the function is called synchronously when handling events. The function should avoid blocking at all costs. For example, any Actions must be run via a separate goroutine.

func (*Chrome) Tab

func (c *Chrome) Tab(indexOfTab int) *Tab

Tab is a getter retrieving a tab. Returns nil upon exception. The `indexOfTab` is an integer within [0, N) where N is the number of tabs created by the browser. E.g. `(*Chrome).Tab(0)` will return the first tab of the browser. Tab(1) for the second one, Tab(2) for the third one and so on.

type Tab

type Tab struct {
	// contains filtered or unexported fields
}

Tab represents a running tab.

func (*Tab) Close

func (t *Tab) Close()

Close closes this tab.

func (*Tab) Dead

func (t *Tab) Dead() <-chan struct{}

Dead returns a channel that's closed when work done on behalf of the tab should be dead. This notifies a user if and only if the browser is dead or `(*Tab).Close()` has been called.

func (*Tab) Do

func (t *Tab) Do() domain.Domain

Do runs a cdproto command on this tab.

func (*Tab) Listen

func (t *Tab) Listen(onEvent func(ev interface{})) error

Listen adds a callback function which will be called whenever an event is received on this tab.

Usage:

t.Listen(func(ev interface{}) {
	switch ev := ev.(type) {
	case *page.EventJavascriptDialogOpening:
		// do something with ev
	case *runtime.EventConsoleAPICalled:
		// do something with ev
	case *runtime.EventExceptionThrown:
		// do something with ev
	}
})

Note that the function is called synchronously when handling events. The function should avoid blocking at all costs. For example, any Actions must be run via a separate goroutine.

func (*Tab) Run

func (t *Tab) Run(actions ...chromedp.Action) error

Run runs a chromedp action on this tab.