webbrowser

Documentation

Index

• type Launcher
  • func NewNativeLauncher() Launcher
• type MockLauncher
  • func NewMockLauncher(ctx context.Context) *MockLauncher
  • func (l *MockLauncher) OpenURL(u string) error
  • func (l *MockLauncher) Wait()

Types

type Launcher

type Launcher interface {
	// OpenURL opens the given URL in a web browser.
	//
	// Depending on the circumstances and on the target platform, this may or
	// may not cause the browser to take input focus. Because of this
	// uncertainty, any caller of this method must be sure to include some
	// language in its UI output to let the user know that a browser tab has
	// opened somewhere, so that they can go and find it if the focus didn't
	// switch automatically.
	OpenURL(url string) error
}

Launcher is an object that knows how to open a given URL in a new tab in some suitable browser on the current system.

Launching of browsers is a very target-platform-sensitive activity, so this interface serves as an abstraction over many possible implementations which can be selected based on what is appropriate for a specific situation.

func NewNativeLauncher

func NewNativeLauncher() Launcher

NewNativeLauncher creates and returns a Launcher that will attempt to interact with the browser-launching mechanisms of the operating system where the program is currently running.

type MockLauncher

type MockLauncher struct {
	// Client is the HTTP client that MockLauncher will use to make requests.
	// By default (if you use NewMockLauncher) this is a new client created
	// via httpclient.New, but callers may override it if they need customized
	// behavior for a particular test.
	//
	// Do not use a client that is shared with any other subsystem, because
	// MockLauncher will customize the settings of the given client.
	Client *http.Client

	// Context can be cancelled in order to abort an OpenURL call before it
	// would naturally complete.
	Context context.Context

	// Responses is a log of all of the responses recieved from the launcher's
	// requests, in the order requested.
	Responses []*http.Response
	// contains filtered or unexported fields
}

MockLauncher is a mock implementation of Launcher that has some special behavior designed for use in unit tests.

When OpenURL is called, MockLauncher will make an HTTP request to the given URL rather than interacting with a "real" browser.

In normal situations it will then return with no further action, but if the response to the given URL is either a standard HTTP redirect response or includes the custom HTTP header X-Redirect-To then MockLauncher will send a follow-up request to that target URL, and continue in this manner until it reaches a URL that is not a redirect. (The X-Redirect-To header is there so that a server can potentially offer a normal HTML page to an actual browser while also giving a next-hop hint for MockLauncher.)

Since MockLauncher is not a full programmable user-agent implementation it can't be used for testing of real-world web applications, but it can be used for testing against specialized test servers that are written with MockLauncher in mind and know how to drive the request flow through whatever steps are required to complete the desired test.

All of the actions taken by MockLauncher happen asynchronously in the background, to simulate the concurrency of a separate web browser. Test code using MockLauncher should provide a context which is cancelled when the test completes, to help avoid leaking MockLaunchers.

func NewMockLauncher

func NewMockLauncher(ctx context.Context) *MockLauncher

NewMockLauncher creates and returns a mock implementation of Launcher, with some special behavior designed for use in unit tests.

See the documentation of MockLauncher itself for more information.

func (*MockLauncher) OpenURL

func (l *MockLauncher) OpenURL(u string) error

OpenURL is the mock implementation of Launcher, which has the special behavior described for type MockLauncher.

func (*MockLauncher) Wait

func (l *MockLauncher) Wait()

Wait blocks until the MockLauncher has finished its asynchronous work of making HTTP requests and following redirects, at which point it will have reached a request that didn't redirect anywhere and stopped iterating.