# kendo-e2e

Selenium based e2e testing for web.

## Getting Started

```bash
npm install @progress/kendo-e2e --save-dev
```

```typescript
import { Browser } from '@progress/kendo-e2e';

describe('My First Test', () => {
    let browser: Browser;

    beforeAll(async () => {
        browser = new Browser();
    });

    afterAll(async () => {
        await browser.close();
    });

    it('should load page and interact', async () => {
        await browser.navigateTo('https://example.com');
        await browser.click('#login-button');
        await browser.type('#username', 'testuser');
        await browser.expect('.welcome-message').toBeVisible();
    });
});
```

## Documentation

- [Getting Started](./docs/GETTING_STARTED.md) - Quick start guide and basic usage
- [API Reference](./docs/API_REFERENCE.md) - Complete API documentation
- [Common Patterns](./docs/PATTERNS.md) - Real-world testing patterns and best practices

### AI/Copilot Integration

kendo-e2e ships with a **CLI + Skills system** designed for AI coding agents (GitHub Copilot, Claude Code, Cursor, etc.). It is ~20-100x more token-efficient than MCP because heavy output (DOM snapshots, screenshots) is saved to disk instead of the context window.

#### Quick Setup

```bash
# Install the AI skill file into your project
npx kendo-e2e install --skills
```

This copies a `SKILL.md` file into `.github/skills/kendo-e2e/` so your AI agent automatically learns how to write kendo-e2e tests.

#### CLI Commands

```bash
npx kendo-e2e open <url>              # Navigate browser to URL
npx kendo-e2e snapshot                 # DOM snapshot → .kendo-e2e/snapshot-*.yaml
npx kendo-e2e snapshot --root ".k-grid" # Zoom into a component
npx kendo-e2e screenshot               # Screenshot → .kendo-e2e/screenshot-*.png
npx kendo-e2e click <selector>         # Click element
npx kendo-e2e type <selector> <text>   # Type into element
npx kendo-e2e find <selector>          # Query element → .kendo-e2e/find-*.json
npx kendo-e2e page-info                # Title, URL, viewport
npx kendo-e2e eval <script>            # Run JavaScript
npx kendo-e2e close                    # Close session
```

#### AI-Powered Workflow

1. **AI navigates** to your application via CLI
2. **AI captures** a DOM snapshot (saved to disk, not in context)
3. **AI reads** the snapshot file to find stable selectors
4. **AI generates** kendo-e2e test code
5. **You run** the generated tests

#### Example

Ask your AI assistant: *"Generate a test for the Kendo Grid filtering on https://demos.telerik.com/kendo-ui/grid"*

The AI will run CLI commands to explore the page and generate:

```typescript
import { Browser } from '@progress/kendo-e2e';

test('should filter grid', async () => {
  const browser = new Browser();
  await browser.navigateTo('https://demos.telerik.com/kendo-ui/grid');
  await browser.click('.k-grid-header .k-filterable');
  await browser.type('.k-filter-menu input', 'John');
  await browser.click('.k-filter-menu .k-primary');
  await browser.expect('.k-grid tbody tr').toHaveCount(5);
  await browser.close();
});
```

### MCP Server (Legacy)

> **⚠️ Deprecated:** The MCP server is being replaced by the CLI above. MCP returns DOM snapshots inline in the context window (~10K-60K+ tokens per session), while CLI saves them to disk (~200-500 tokens). Use the CLI for agents with shell access. MCP remains available for sandboxed environments (e.g., Claude Desktop) where shell access is not available.

<details>
<summary>MCP Setup (for sandboxed environments)</summary>

Add to your MCP settings (Claude Desktop or VS Code):

```json
{
  "mcpServers": {
    "kendo-e2e": {
      "command": "npx",
      "args": ["-p", "@progress/kendo-e2e", "kendo-e2e-mcp"]
    }
  }
}
```

See [MCP Server Documentation](./src/mcp/README.md) for detailed tool reference.

</details>