119 lines
3.4 KiB
Markdown
119 lines
3.4 KiB
Markdown
---
|
|
name: ck-agent-browser
|
|
description: >
|
|
Automates browser interactions using headless or visible browser control.
|
|
Activate when user says 'automate browser', 'scrape website', 'browser automation',
|
|
'navigate to URL and extract', 'click buttons on webpage', or 'test UI in browser'.
|
|
Accepts URLs, CSS selectors, XPath, interaction sequences, and screenshot requests.
|
|
---
|
|
|
|
## Overview
|
|
Drives browser automation tasks including navigation, form filling, clicking, scraping, and screenshot capture. Uses Playwright or Puppeteer patterns for reliable cross-browser automation.
|
|
|
|
## When to Use
|
|
- User needs to scrape data from a website that requires JavaScript rendering
|
|
- Automating multi-step browser workflows (login → navigate → extract)
|
|
- Taking screenshots of web pages for visual testing or documentation
|
|
- Filling and submitting forms programmatically
|
|
- End-to-end browser testing without a test framework
|
|
- Checking page content or structure of a live URL
|
|
|
|
## Don't Use When
|
|
- The target site provides a public REST or GraphQL API (use the API instead)
|
|
- Simple static HTML scraping (use fetch + HTML parser)
|
|
- Running unit or component tests (use ck-web-testing instead)
|
|
- The task requires human verification (CAPTCHA, MFA flows)
|
|
|
|
## Steps / Instructions
|
|
|
|
### 1. Identify Automation Goal
|
|
Clarify:
|
|
- Target URL(s)
|
|
- Actions required: navigate, click, type, scroll, wait, extract, screenshot
|
|
- Expected output: text, JSON, screenshot file, assertion result
|
|
|
|
### 2. Choose Automation Approach
|
|
|
|
```
|
|
Playwright (preferred):
|
|
- Cross-browser (Chromium, Firefox, WebKit)
|
|
- Auto-waits for elements
|
|
- Built-in screenshot / PDF
|
|
- Network interception support
|
|
|
|
Puppeteer:
|
|
- Chromium/Chrome only
|
|
- Fine-grained CDP access
|
|
- Slightly lighter for simple scraping
|
|
```
|
|
|
|
### 3. Write Automation Script
|
|
|
|
```typescript
|
|
// Playwright example
|
|
import { chromium } from 'playwright';
|
|
|
|
async function run() {
|
|
const browser = await chromium.launch({ headless: true });
|
|
const page = await browser.newPage();
|
|
|
|
await page.goto('https://example.com');
|
|
await page.waitForSelector('.target-element');
|
|
|
|
const text = await page.textContent('.target-element');
|
|
console.log(text);
|
|
|
|
await page.screenshot({ path: 'screenshot.png', fullPage: true });
|
|
await browser.close();
|
|
}
|
|
|
|
run();
|
|
```
|
|
|
|
### 4. Handle Common Patterns
|
|
|
|
**Login flow:**
|
|
```typescript
|
|
await page.fill('#username', process.env.USERNAME!);
|
|
await page.fill('#password', process.env.PASSWORD!);
|
|
await page.click('[type="submit"]');
|
|
await page.waitForURL('**/dashboard');
|
|
```
|
|
|
|
**Extract structured data:**
|
|
```typescript
|
|
const items = await page.$$eval('.product-card', cards =>
|
|
cards.map(card => ({
|
|
title: card.querySelector('h2')?.textContent?.trim(),
|
|
price: card.querySelector('.price')?.textContent?.trim(),
|
|
}))
|
|
);
|
|
```
|
|
|
|
**Wait for network idle:**
|
|
```typescript
|
|
await page.goto(url, { waitUntil: 'networkidle' });
|
|
```
|
|
|
|
### 5. Error Handling
|
|
|
|
```typescript
|
|
try {
|
|
await page.waitForSelector('.element', { timeout: 5000 });
|
|
} catch {
|
|
console.error('Element not found within timeout');
|
|
await page.screenshot({ path: 'error-state.png' });
|
|
}
|
|
```
|
|
|
|
### 6. Output Results
|
|
- Return extracted data as JSON
|
|
- Save screenshots to a designated output directory
|
|
- Log errors with page URL and selector context
|
|
|
|
## Notes
|
|
- Never hardcode credentials; use environment variables
|
|
- Respect robots.txt and site terms of service
|
|
- Add realistic delays for sites with rate limiting
|
|
- Use `--no-sandbox` flag only in trusted CI environments
|