@progress/kendo-e2e 4.11.2 → 4.12.0

package/README.md

@@ -1,130 +1,52 @@
-
-![Kendo UI Logo](https://www.telerik.com/kendo-angular-ui/npm-banner.svg)
-
-## Professional Grade UI Components
-
-This package is part of the [Kendo UI for Angular](https://www.telerik.com/kendo-angular-ui/) and [KendoReact](https://www.telerik.com/kendo-react-ui/components/#react-components) suites.
-
-## License
-
-This is commercial software. To use it, you need to agree to the [**Telerik End User License Agreement for Kendo UI** (for Kendo UI for Angular)](http://www.telerik.com/purchase/license-agreement/kendo-ui) or to the [**End User License Agreement for Progress KendoReact** (for KendoReact)](https://www.telerik.com/purchase/license-agreement/progress-kendoreact). If you do not own a commercial license, this file shall be governed by the trial license terms.
-
-All available Kendo UI commercial licenses may be obtained at http://www.telerik.com/purchase/kendo-ui.
-
-## Kendo UI for Angular Resources and Feedback
-
-- [Get Started](https://www.telerik.com/kendo-angular-ui/getting-started)
-- [Component References](https://www.telerik.com/kendo-angular-ui/components)
-- [Blogs](http://www.telerik.com/blogs/kendo-ui)
-- [FAQ](https://www.telerik.com/kendo-angular-ui/components/faq/)
-- [GitHub Issues](https://github.com/telerik/kendo-angular/issues)
-- [Feedback Portal](http://kendoui-feedback.telerik.com/forums/555517-kendo-ui-for-angular-2-feedback)
-- [StackOverflow](https://stackoverflow.com/questions/tagged/kendo-ui-angular2)
-
-## KendoReact Resources and Feedback
-
-- [Get Started](https://www.telerik.com/kendo-react-ui/getting-started)
-- [Component References](https://www.telerik.com/kendo-react-ui/components/#react-components)
-- [Blogs](http://www.telerik.com/blogs/kendo-ui)
-- [GitHub Issues](https://github.com/telerik/kendo-react/issues)
-- [Feedback Portal](http://kendoui-feedback.telerik.com/forums/908425-kendo-ui-for-react-feedback)
-- [StackOverflow](https://stackoverflow.com/questions/tagged/kendo-react-ui)
-
-*Copyright © 2021 Progress Software Corporation and/or its subsidiaries or affiliates. All Rights Reserved.*
-
-*Progress, Telerik, and certain product names used herein are trademarks or registered trademarks of Progress Software Corporation and/or one of its subsidiaries or affiliates in the U.S. and/or other countries.*
-
 # kendo-e2e
 
 Selenium based e2e testing for web.
 
-## Usage
-
-### Managing browsers
-
-Example:
-
-```javascript
-    const browser = new Browser();
-    await browser.navigateTo("https://www.telerik.com/")
-    await browser.close();
-```
-
-By default it will start Chrome browser with size 1366x768.
-
-Browser type and size can be controlled by settings following environment variables:
-
-- `BROWSER_NAME`
-
-    Allowed values are `chrome`, `firefox`, `MicrosoftEdge` and `safari` (default is `chrome`).
+## Getting Started
 
-- `BROWSER_WIDTH` and `BROWSER_HEIGHT`
-
-    Default values are `1366` and `768`.
-
-- `HEADLESS`
-
-    If set to `true` it will start browsers in headless mode (default is `false`).
-
-    Notes: `Safari` do not support headless mode and this setting will be ignored.
-
-### Find Elements and Wait for Conditions
-
-Selenium default behavior when you search for element is to return it if available and throw if not available (do not try to wait until element is available).
-
-To make writing e2e tests easier and tests more stable in `kendo-e2e` we have:
-
-```js
-    const element = await browser.find(locator, timeout);
+```bash
+npm install @progress/kendo-e2e --save-dev
 ```
 
-This `find` with wait until element is available (until timeout reached), if timeout reached and element still not found it will throw.
+```typescript
+import { Browser } from '@progress/kendo-e2e';
 
-### Detect JavaScript errors in Browser Logs
-
-```js
-    await browser.getErrorLogs()
-```
+describe('My First Test', () => {
+    let browser: Browser;
 
-Will return all errors in browser console and it is nice check we can perform after each test to ensure we have no missing resources or scripts throwing errors.
+    beforeAll(async () => {
+        browser = new Browser();
+    });
 
-### Detect Accessibility Violations
+    afterAll(async () => {
+        await browser.close();
+    });
 
-```js
-    const disableRules = ['aria-allowed-role', 'label'];
-    const errors = await browser.getAccessibilityViolations('#table', disableRules);
-    expect(errors).toEqual([]);
+    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();
+    });
+});
 ```
 
-`getAccessibilityViolations` uses [axe](https://www.deque.com/axe/) to detect WCAG 2.1 violations.
+## Documentation
 
-### Kendo UI Components Abstractions
+- [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
 
-TODO
+### AI/Copilot Integration
 
-## Contribution
+To get better AI-powered suggestions when writing tests, you can create a `.github/copilot-instructions.md` file in your project:
 
-PRs are welcome!
+```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.
 
-Lint:
-
-```bash
-npm run lint
-```
-
-Build:
-
-```bash
-npm run build
-```
-
-Run tests:
-
-```bash
-npm run test:a11y
-npm run test:e2e
-npm run test:visual
-npm run test:components
-npm run test:rendering
-npm run test:snapshot
+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
 ```

package/dist/selenium/browser.d.ts

@@ -14,10 +14,46 @@ interface BrowserOptions {
     enableBidi?: boolean;
 }
 /**
- * Extends the {@link WebApp} with browser based capabilities.
- * Essentially, we test browsers (that have nice things like {@link navigateTo}, {@link refresh} etc.),
- * and electron apps, that render within a webview (but have no shell with address bar, refresh button, tabs, etc),
- * and VSCode extensions... which is an electron app.
+ * Browser automation class with automatic waiting and modern web testing features.
+ *
+ * Extends {@link WebApp} with browser-specific capabilities like navigation, window management,
+ * accessibility testing, and console log monitoring. Perfect for testing web applications in
+ * real browsers (Chrome, Firefox, Safari, Edge).
+ *
+ * **Key features:**
+ * - Browser navigation and URL management
+ * - Window resizing and iframe handling
+ * - Mobile device emulation
+ * - Accessibility (a11y) testing with axe-core
+ * - Console error detection
+ * - BiDi protocol support
+ *
+ * @example
+ * ```typescript
+ * // Basic browser test
+ * const browser = new Browser();
+ * await browser.navigateTo('https://example.com');
+ * await browser.click('#login-button');
+ * await browser.expect('.welcome-message').toBeVisible();
+ * await browser.close();
+ *
+ * // Mobile emulation
+ * const mobile = new Browser({ mobileEmulation: { deviceName: 'iPhone 14 Pro Max' } });
+ * await mobile.navigateTo('https://example.com');
+ *
+ * // With BiDi for advanced features
+ * const browser = new Browser({ enableBidi: true });
+ *
+ * // Check for console errors
+ * await browser.clearLogs();
+ * await browser.click('#trigger-error');
+ * const errors = await browser.getErrorLogs();
+ * expect(errors).toHaveLength(0);
+ *
+ * // Accessibility testing
+ * const violations = await browser.getAccessibilityViolations();
+ * expect(violations).toHaveLength(0);
+ * ```
  */
 export declare class Browser extends WebApp {
     /**
@@ -70,7 +106,47 @@ export declare class Browser extends WebApp {
         height: number;
         pixelRatio: number;
     } | any, enableBidi?: boolean);
+    /**
+     * Closes the browser and ends the WebDriver session.
+     *
+     * Should be called at the end of each test to clean up resources.
+     * Closes all browser windows and terminates the driver.
+     *
+     * @returns Promise that resolves when browser is closed
+     *
+     * @example
+     * ```typescript
+     * const browser = new Browser();
+     * try {
+     *   await browser.navigateTo('https://example.com');
+     *   // ... test code ...
+     * } finally {
+     *   await browser.close(); // Always close to free resources
+     * }
+     * ```
+     */
     close(): Promise<void>;
+    /**
+     * Navigates the browser to a specified URL.
+     *
+     * Opens the URL in the current browser window. Waits for the page to load before
+     * the promise resolves.
+     *
+     * @param url - The URL to navigate to (must include protocol: http:// or https://)
+     * @returns Promise that resolves when navigation completes
+     *
+     * @example
+     * ```typescript
+     * // Navigate to a website
+     * await browser.navigateTo('https://example.com');
+     *
+     * // Navigate to local development server
+     * await browser.navigateTo('http://localhost:3000');
+     *
+     * // Navigate to specific page
+     * await browser.navigateTo('https://example.com/products/123');
+     * ```
+     */
     navigateTo(url: string): Promise<void>;
     getRect(): Promise<IRectangle>;
     setRect(rect: {
@@ -97,12 +173,177 @@ export declare class Browser extends WebApp {
      * ```
      */
     resizeWindow(width: number, height: number): Promise<void>;
+    /**
+     * Refreshes the current page (like pressing F5 or clicking browser refresh).
+     *
+     * Reloads the page from the server, resetting all JavaScript state.
+     *
+     * @returns Promise that resolves when page reload completes
+     *
+     * @example
+     * ```typescript
+     * // Refresh after making changes
+     * await browser.click('#update-settings');
+     * await browser.refresh();
+     *
+     * // Verify data persists after refresh
+     * await browser.type('#input', 'test');
+     * await browser.click('#save');
+     * await browser.refresh();
+     * const value = await browser.getAttribute('#input', 'value');
+     * expect(value).toBe('test');
+     * ```
+     */
     refresh(): Promise<void>;
+    /**
+     * Switches the WebDriver context to an iframe.
+     *
+     * After calling this, all subsequent commands will target elements within the iframe.
+     * To switch back to the main page, use `driver.switchTo().defaultContent()`.
+     *
+     * @param elementLocator - By locator for the iframe element
+     * @returns Promise that resolves when context is switched
+     *
+     * @example
+     * ```typescript
+     * // Switch to iframe and interact with its content
+     * await browser.switchToIFrame(By.css('#my-iframe'));
+     * await browser.click('#button-inside-iframe');
+     *
+     * // Switch back to main page
+     * await browser.driver.switchTo().defaultContent();
+     * await browser.click('#button-on-main-page');
+     *
+     * // Work with nested iframes
+     * await browser.switchToIFrame(By.css('#outer-frame'));
+     * await browser.switchToIFrame(By.css('#inner-frame'));
+     * ```
+     */
     switchToIFrame(elementLocator: By): Promise<void>;
+    /**
+     * Gets the current URL of the browser.
+     *
+     * Returns the complete URL including protocol, domain, path, and query parameters.
+     *
+     * @returns Promise resolving to the current URL string
+     *
+     * @example
+     * ```typescript
+     * // Verify navigation occurred
+     * await browser.click('#products-link');
+     * const url = await browser.getCurrentUrl();
+     * expect(url).toContain('/products');
+     *
+     * // Check URL parameters
+     * const currentUrl = await browser.getCurrentUrl();
+     * expect(currentUrl).toContain('?filter=active');
+     *
+     * // Verify redirect
+     * await browser.navigateTo('http://example.com/old-page');
+     * const redirectedUrl = await browser.getCurrentUrl();
+     * expect(redirectedUrl).toBe('http://example.com/new-page');
+     * ```
+     */
     getCurrentUrl(): Promise<string>;
+    /**
+     * Gets the name of the current browser.
+     *
+     * Returns lowercase browser name: 'chrome', 'firefox', 'safari', 'edge', etc.
+     * Useful for browser-specific test logic.
+     *
+     * @returns Promise resolving to lowercase browser name
+     *
+     * @example
+     * ```typescript
+     * const browserName = await browser.getBrowserName();
+     *
+     * if (browserName === 'safari') {
+     *   // Skip Safari-incompatible test
+     *   console.log('Skipping on Safari');
+     *   return;
+     * }
+     *
+     * // Browser-specific assertions
+     * if (browserName === 'firefox') {
+     *   // Firefox-specific validation
+     * }
+     * ```
+     */
     getBrowserName(): Promise<string>;
+    /**
+     * Runs accessibility (a11y) tests using axe-core and returns violations.
+     *
+     * Scans the page for accessibility issues like missing alt text, insufficient color contrast,
+     * missing ARIA labels, etc. Returns an array of violations that should be addressed.
+     *
+     * @param cssSelector - CSS selector to limit scanning scope (default: 'html' for full page)
+     * @param disableRules - Array of axe rule IDs to disable (default: ['color-contrast'])
+     * @returns Promise resolving to array of accessibility violations
+     *
+     * @example
+     * ```typescript
+     * // Scan entire page
+     * const violations = await browser.getAccessibilityViolations();
+     * expect(violations).toHaveLength(0);
+     *
+     * // Scan specific component
+     * const formViolations = await browser.getAccessibilityViolations('#login-form');
+     *
+     * // Enable all rules including color contrast
+     * const allViolations = await browser.getAccessibilityViolations('html', []);
+     *
+     * // Disable specific rules
+     * const violations = await browser.getAccessibilityViolations('html', [
+     *   'color-contrast',
+     *   'landmark-one-main'
+     * ]);
+     * ```
+     */
     getAccessibilityViolations(cssSelector?: string, disableRules?: string[]): Promise<[]>;
+    /**
+     * Clears the browser console logs.
+     *
+     * Call this before performing actions to get a clean slate for error detection.
+     * Useful when you want to check if a specific action causes console errors.
+     *
+     * @returns Promise that resolves when logs are cleared
+     *
+     * @example
+     * ```typescript
+     * // Clear logs before action
+     * await browser.clearLogs();
+     * await browser.click('#potential-error-button');
+     * const errors = await browser.getErrorLogs();
+     * ```
+     */
     clearLogs(): Promise<void>;
+    /**
+     * Gets console errors from the browser (Chrome only).
+     *
+     * Retrieves console errors logged by the browser. Only works in Chrome on desktop platforms.
+     * Firefox and mobile platforms don't support log retrieval.
+     *
+     * @param excludeList - Array of strings to filter out from errors (default: ['favicon.ico'])
+     * @param logLevel - Minimum log level to collect (default: Level.SEVERE for errors)
+     * @returns Promise resolving to array of error message strings
+     *
+     * @example
+     * ```typescript
+     * // Check for any console errors
+     * const errors = await browser.getErrorLogs();
+     * expect(errors.length).toBe(0);
+     *
+     * // Exclude known non-critical errors
+     * const errors = await browser.getErrorLogs(['favicon', 'analytics']);
+     *
+     * // Get all warnings and errors
+     * const logs = await browser.getErrorLogs([], Level.WARNING);
+     *
+     * // Check for specific error
+     * const errors = await browser.getErrorLogs();
+     * expect(errors.some(e => e.includes('TypeError'))).toBe(false);
+     * ```
+     */
     getErrorLogs(excludeList?: string[], logLevel?: Level): Promise<string[]>;
     /**
      * Executes a JavaScript script in the browser context.