@progress/kendo-e2e/README.md

Kendo UI end-to-end test utilities.

# 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

To get better AI-powered suggestions when writing tests, you can create a `.github/copilot-instructions.md` file in your project:

```markdown
When writing e2e tests with @progress/kendo-e2e, refer to the documentation in 
node_modules/@progress/kendo-e2e/docs/ for patterns, API usage, and best practices.

Key points:
- Browser is started once in beforeAll, closed in afterAll
- All interactions have automatic waiting built-in
- Avoid Page Object pattern for simple component tests
```

### AI/MCP Server

kendo-e2e includes a **Model Context Protocol (MCP) server** that enables AI assistants (like Claude Desktop or GitHub Copilot) to directly interact with browsers for intelligent test generation.

#### Quick Setup

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

```json
{
  "mcpServers": {
    "kendo-e2e": {
      "command": "npx",
      "args": ["-y", "@progress/kendo-e2e/dist/mcp/index.js"]
    }
  }
}
```

Or run directly:

```bash
npx kendo-e2e-mcp
```

#### What It Enables

The MCP server provides AI assistants with 8 powerful tools:

- **Browser control** - Navigate, execute scripts, manage sessions
- **Smart DOM snapshots** - Get filtered page structure with Kendo component detection
- **Selector testing** - Validate CSS/XPath selectors before generating code
- **Element interactions** - Click, type, hover with automatic waiting
- **Element queries** - Check visibility, text, attributes

#### AI-Powered Workflow

1. **AI navigates** to your application
2. **AI analyzes** page structure using DOM snapshots
3. **AI tests** selectors to find stable locators
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:
1. Navigate to the page
2. Capture DOM structure (detecting Kendo widgets via `data-role` attributes)
3. Test selectors to find reliable locators
4. Generate clean kendo-e2e test code:

```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();
});
```

#### Benefits

- ✅ **Context-aware** - AI understands your page structure
- ✅ **Kendo-optimized** - Detects Kendo widgets automatically
- ✅ **Fast iteration** - Test and refine selectors before generating code
- ✅ **No manual exploration** - AI discovers elements for you

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