Flash Test Framework

A powerful, keyword-driven automation framework built on top of Playwright and TypeScript, featuring AI-powered capabilities.

Quick Start

The easiest way to start a new project is using our CLI.

Global Installation

Alternatively, you can install the CLI globally to run flash-test commands directly.

npm install -g @flash-ai-team/flash-test-framework

Then you can use:

flash-test init <project-name>
flash-test run <suite-name> [-browser <browser>]
flash-test latest-run <suite-name>
flash-test history [suite-name]
flash-test --version

Commands

• init <project-name>: Initialize a new project structure.
• run <suite-name>: Run a specific test suite.
  • Example: flash-test run parallel_suite
  • Example: flash-test run parallel_suite -browser firefox
• latest-run <suite-name>: View the status of the most recent run for a suite.
  • Example: flash-test latest-run parallel_suite
• history [suite-name]: View historical test runs and open the HTML dashboard.
  • Example: flash-test history (All suites)
  • Example: flash-test history parallel_suite (Specific suite)
• --version: Show CLI version.

1. Initialize a new project: Make a new folder and run:

   flash-test init <project-name>

   This will create:

   • package.json with dependencies.
   • playwright.config.ts configured for the framework.
   • tsconfig.json.
   • tests/cases/ExampleTests.ts and tests/suites/Example.spec.ts.

2. Install dependencies:

   npm install

3. Run the test:

   npx playwright test

Manual Setup (Optional)

If you prefer to set up manually:

1. npm install @flash-ai-team/flash-test-framework
2. Create playwright.config.ts and tsconfig.json.
3. Email Reporting: Create email.config.json.
4. AI Features: Create ai.config.json:

   {
       "enabled": true,
       "provider": "openai",
       "apiKey": "sk-...",
       "model": "gpt-4o"
   }

Usage

1. Basic Web Automation (Web)

Use Web for standard, deterministic interactions using selectors. Import test from the framework to automatically initialize the context.

import { test, Web, el, KeywordContext } from '@flash-ai-team/flash-test-framework';

test.describe('My Test Suite', () => {
    // Context is automatically initialized by the 'test' fixture

    test('Login Test', async () => {
        await Web.navigateToUrl('https://example.com/login');
        
        const usernameInput = el('#username', 'Username Field');
        const passwordInput = el('#password', 'Password Field');
        const loginButton = el('button[type="submit"]', 'Login Button');

        await Web.setText(usernameInput, 'myuser');
        await Web.setText(passwordInput, 'mypassword');
        await Web.click(loginButton);
        
        // precise search using heuristics
        await Web.search("Specific Item");
    });
});

2. AI & Manual Steps (AIWeb)

Use AIWeb to write tests in plain English or to click elements that are hard to target (like map markers) using images.

Example: AIManualSteps.spec.ts

import { test, AIWeb } from '@flash-ai-team/flash-test-framework';

test.describe('AI Scenario', () => {

    test('Google Maps Flow', async () => {
        await AIWeb.executeManualSteps(`
            1. Navigate to "https://www.google.com/maps"
            2. Click on "Accept all"
            3. Search "KFC"
            4. Press Enter
            5. Click on the marker image
        `);
    });
});

Key Features:

• Natural Language Parsing: "Click", "Navigate", "Search", "Press Key".
• Image Matching: Place an image (e.g., marker.png) in tests/assets/. If you write Click on "marker image", the framework will look for tests/assets/marker.png and click it on the screen.
• Heuristic Search: Search "text" automatically finds search bars.

Keywords

Core Helpers

• el(selector, description?): Creates a Test Object.
  • selector (string): The CSS selector, XPath, or Playwright selector (e.g. text=Submit, role=button[name="Login"]).
  • description (string): Optional description for reporting logs.

Web

Navigation

• navigateToUrl(url): Navigate to the specified URL.
• refresh(): Refresh the current page.
• back(): Navigate back.
• forward(): Navigate forward.
• closeBrowser(): Close the browser instance.
• verifyUrl(url, timeout?): Verify the current URL matches the expected URL.

Interaction

• click(testObject): Click on a test object.
• doubleClick(testObject): Double-click on a test object.
• rightClick(testObject): Right-click on a test object.
• setText(testObject, text): Clear and set text in an input field.
• sendKeys(testObject, key): Send specific keys to an element.
• pressKey(key): Press a specific key globally (e.g., 'Enter').
• check(testObject): Check a checkbox or radio button.
• uncheck(testObject): Uncheck a checkbox.
• selectOptionByValue(testObject, value): Select a dropdown option by value.
• selectOptionByLabel(testObject, label): Select a dropdown option by label.
• mouseOver(testObject): Hover over an element.
• dragAndDrop(source, target): Drag one element and drop it onto another.
• uploadFile(testObject, absolutePath): Upload a file to an input element.
• scrollToElement(testObject): Scroll the page to make the element visible.
• search(text): Heuristically find a search bar and enter text.
• clickImage(imagePath): Click an element by matching an image template.

Verification

• verifyElementPresent(testObject, timeout?): Assert an element exists.
• verifyElementNotPresent(testObject, timeout?): Assert an element does not exist.
• verifyElementText(testObject, expectedText): Assert element text matches.
• verifyElementAttributeValue(testObject, attribute, value): Assert element attribute matches.
• verifyElementChecked(testObject, checked?): Assert element checked state.
• verifyElementClickable(testObject, timeout?): Assert element is visible and enabled.
• verifyTextPresent(text): Assert text exists on the page.

Synchonization

• waitForElementVisible(testObject, timeout?): Wait for element to be visible.
• waitForElementNotVisible(testObject, timeout?): Wait for element to disappear.
• waitForElementClickable(testObject, timeout?): Wait for element to be clickable.
• waitForPageLoad(timeout?, state?): Wait for page load state ('load', 'domcontentloaded', 'networkidle').
• waitForNextPageLoaded(timeout?, waitUntil?): Wait for next navigation to complete.
• waitForAngularLoad(): Wait for Angular stability (if applicable).
• delay(seconds): Hard wait (use sparingly).

Utilities

• getText(testObject): Get text content of an element.
• getAttribute(testObject, attribute): Get attribute value of an element.
• takeScreenshot(filename?): Capture a full-page screenshot.
• maximizeWindow(): Maximize the browser window.
• setWindowSize(width, height): Set specific window dimensions.

AIWeb

• executeManualSteps(steps: string): Execute a multi-step test case described in natural language.

Support

If you have any concerns or questions, please contact us at [email protected].