Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ParseBrowserEnv ¶
ParseBrowserEnv takes the raw value of a BROWSER environment variable and attempts to parse it as a reference to an executable, whose absolute path is returned if successful. Returns an empty string if the value cannot be interpreted as an executable to run.
This implements the simple form of this environment variable commonly used by software on Unix-like systems, where the value must be literally just a command to run whose first and only argument would be the URL to open.
It does NOT support the more complex interpretation of that environment variable that was proposed at http://www.catb.org/~esr/BROWSER/ , because that form has not been widely implemented and the implementations that exist do not have consistent behavior due to the proposal being ambiguous.
Callers that use this should typically pass a successful result to NewExecLauncher to use the resolved command as a browser launcher. The caller is responsible for deciding the policy for whether to consider a BROWSER environment variable and for accessing the environment table to obtain its value.
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 NewExecLauncher ¶
NewExecLauncher creates and returns a Launcher that just attempts to run the executable at the given path, with the given URL as its first and only argument.
The given path must be ready to use, without reference to the PATH environment variable. The caller can use exec.LookPath to prepare a suitable path if searching PATH is appropriate.
This is intended to allow overriding which browser to use using the BROWSER environment variable on Unix-like systems, but the rules for that are in "package main". ParseBrowserEnv implements parsing of the value of that environment variable when the main package decides it's appropriate to do so.
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 received 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.
Source Files