diff --git a/Getting-Started.-.md b/Getting-Started.-.md deleted file mode 100644 index fec7a68..0000000 --- a/Getting-Started.-.md +++ /dev/null @@ -1,225 +0,0 @@ -# Getting Started - -This guide covers prerequisites, connection options, and basic browser interaction with go-webview. - -## Prerequisites - -You need a Chrome or Chromium browser running with remote debugging enabled. Start it from the command line: - -```bash -# Linux -google-chrome --remote-debugging-port=9222 - -# macOS -/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 - -# Headless mode (no GUI) -google-chrome --headless --remote-debugging-port=9222 -``` - -The `--remote-debugging-port` flag exposes Chrome's DevTools Protocol over HTTP and WebSocket on the specified port. The package connects to this endpoint to control the browser. - -## Connection Options - -Create a `Webview` instance using `New()` with one or more `Option` functions: - -### WithDebugURL - -Required. Specifies the Chrome DevTools HTTP endpoint: - -```go -wv, err := webview.New( - webview.WithDebugURL("http://localhost:9222"), -) -``` - -Under the hood, this calls `NewCDPClient()` which: -1. Fetches available targets from `http://localhost:9222/json` -2. Finds the first `"page"` type target with a WebSocket debugger URL -3. If no page target exists, creates one via `/json/new` -4. Opens a WebSocket connection to the target - -### WithTimeout - -Sets the default timeout for all operations. Defaults to 30 seconds: - -```go -wv, err := webview.New( - webview.WithDebugURL("http://localhost:9222"), - webview.WithTimeout(60 * time.Second), -) -``` - -Each method on `Webview` creates a `context.WithTimeout` using this duration for its CDP calls. - -### WithConsoleLimit - -Sets the maximum number of console messages retained in the built-in buffer. Defaults to 1000: - -```go -wv, err := webview.New( - webview.WithDebugURL("http://localhost:9222"), - webview.WithConsoleLimit(5000), -) -``` - -When the limit is reached, the oldest messages are pruned in batches of 100. - -## Navigation - -```go -// Navigate to a URL (waits for page load) -err := wv.Navigate("https://example.com") - -// Reload the current page -err = wv.Reload() - -// Go back in history -err = wv.GoBack() - -// Go forward in history -err = wv.GoForward() -``` - -`Navigate` and `Reload` both poll `document.readyState` every 100ms until it equals `"complete"`, subject to the configured timeout. - -## Page Information - -```go -// Get the current URL -url, err := wv.GetURL() - -// Get the page title -title, err := wv.GetTitle() - -// Get the full document HTML (pass empty string for whole page) -html, err := wv.GetHTML("") - -// Get the outer HTML of a specific element -elemHTML, err := wv.GetHTML("#main-content") -``` - -## Basic Interaction - -```go -// Click an element by CSS selector -err := wv.Click("#submit-button") - -// Type text into an input field -err = wv.Type("#email-input", "user@example.com") - -// Wait for an element to appear in the DOM -err = wv.WaitForSelector(".loaded-content") -``` - -`Click` resolves the element's bounding box via CDP and dispatches `mousePressed`/`mouseReleased` events at the element's centre. If the bounding box cannot be determined, it falls back to a JavaScript `element.click()`. - -`Type` focuses the element first, then dispatches `keyDown`/`keyUp` events for each character. - -## Viewport and User Agent - -```go -// Set viewport dimensions -err := wv.SetViewport(1920, 1080) - -// Override the user agent string -err = wv.SetUserAgent("Custom Agent/1.0") -``` - -These use the CDP `Emulation` domain under the hood. - -## Screenshots - -```go -// Capture a PNG screenshot -pngData, err := wv.Screenshot() - -// Write to file -os.WriteFile("page.png", pngData, 0644) -``` - -Returns raw PNG bytes using `Page.captureScreenshot`. - -## JavaScript Evaluation - -```go -// Execute JavaScript and get the return value -result, err := wv.Evaluate("document.querySelectorAll('a').length") -// result is an any -- in this case, a float64 - -// Execute a void script -_, err = wv.Evaluate("document.body.style.background = 'red'") -``` - -Scripts are evaluated via `Runtime.evaluate` with `returnByValue: true`. If the script throws, the error is returned as a Go error prefixed with `"JavaScript error:"`. - -## Console Messages - -Console messages are automatically captured from the moment the `Webview` is created: - -```go -// Get all captured console messages -messages := wv.GetConsole() -for _, msg := range messages { - fmt.Printf("[%s] %s -", msg.Type, msg.Text) -} - -// Clear the buffer -wv.ClearConsole() -``` - -For advanced filtering and real-time watching, see [[Console-Monitoring]]. - -## File Upload and Drag & Drop - -```go -// Upload files to a file input element -err := wv.UploadFile("#file-input", []string{"/path/to/file.pdf"}) - -// Drag and drop between elements -err = wv.DragAndDrop("#source-item", "#drop-target") -``` - -`UploadFile` uses `DOM.setFileInputFiles`. `DragAndDrop` dispatches a sequence of `mousePressed`, `mouseMoved`, and `mouseReleased` events between the source and target element centres. - -## Low-Level CDP Client - -For advanced use cases, you can work directly with `CDPClient`: - -```go -// List all browser targets -targets, err := webview.ListTargets("http://localhost:9222") - -// Get Chrome version info -version, err := webview.GetVersion("http://localhost:9222") - -// Create a new tab -client, err := existingClient.NewTab("https://example.com") -defer client.Close() - -// Register an event handler -client.OnEvent("Page.loadEventFired", func(params map[string]any) { - fmt.Println("Page loaded!") -}) - -// Make a raw CDP call -result, err := client.Call(ctx, "DOM.getDocument", nil) -``` - -## Cleanup - -Always close the `Webview` when finished: - -```go -defer wv.Close() -``` - -This cancels the internal context and closes the WebSocket connection to Chrome. - -## Next Steps - -- [[DOM-Queries]] -- Querying and inspecting DOM elements -- [[Actions]] -- Chainable action sequences -- [[Console-Monitoring]] -- Advanced console watching and filtering -- [[Angular-Testing]] -- Angular-specific testing utilities