### Fork and Install Testplane Locally

Source: https://github.com/gemini-testing/testplane/blob/master/CONTRIBUTING.md

Steps to clone the Testplane repository from GitHub, navigate into the directory, and install dependencies using npm. This is the first step for local development.

```bash
git clone https://github.com/gemini-testing/testplane.git # Replace with your fork URL
cd testplane
npm install
```

--------------------------------

### Initialize New Testplane Project with Wizard (Bash)

Source: https://context7.com/gemini-testing/testplane/llms.txt

Command to initialize a new Testplane project using the latest version and its interactive setup wizard. This is the recommended approach for starting a new project.

```bash
npm init testplane@latest new-testplane-project
```

--------------------------------

### Initialize Testplane Project via npm

Source: https://github.com/gemini-testing/testplane/blob/master/docs/quick-start.md

This command initializes a new Testplane project using the `create-testplane` tool. It prompts the user with a series of questions to configure the project. The `-y` option can be used to skip all prompts and use default configurations.

```bash
npm init testplane YOUR_PROJECT_PATH
```

--------------------------------

### INIT Event Handler Example for Plugin Setup

Source: https://github.com/gemini-testing/testplane/blob/master/docs/events/init.md

This example shows a common use case for the INIT event within a plugin. It parses configuration options, checks if the plugin is enabled and not in a worker context, and then subscribes to the INIT event to perform setup actions. Dependencies include a local 'config' module.

```javascript
const parseConfig = require('./config');

module.exports = (testplane, opts) => {
    const pluginConfig = parseConfig(opts);

    if (!pluginConfig.enabled || testplane.isWorker()) {
        // either the plugin is disabled, or we are in the worker context - leave
        return;
    }

    testplane.on(testplane.events.INIT, () => {
        // do something
    });
};
```

--------------------------------

### Run Testplane Tests

Source: https://github.com/gemini-testing/testplane/blob/master/docs/quick-start.md

This command executes the configured Testplane tests. It is assumed that the necessary browser drivers (e.g., ChromeDriver) and Selenium Standalone Server are already running or accessible.

```bash
node_modules/.bin/testplane
```

--------------------------------

### Write a Basic Testplane Test

Source: https://github.com/gemini-testing/testplane/blob/master/docs/quick-start.md

This JavaScript code defines a simple Testplane test case. It navigates to the Testplane GitHub repository page and asserts that the main heading has the expected text 'Testplane (ex-Hermione)'. It requires a running browser instance.

```javascript
describe('github', function() {
    it('should check repository name', async ({ browser }) => {
        await browser.url('https://github.com/gemini-testing/testplane');

        await expect(browser.$('#readme h1')).toHaveText('Testplane (ex-Hermione)');
    });
});
```

--------------------------------

### Install and Run Selenium Standalone

Source: https://github.com/gemini-testing/testplane/blob/master/docs/dealing-with-browsers.md

Installs the selenium-standalone package globally, installs necessary browser drivers, and starts the Selenium server. Requires Java Development Kit (JDK) if Java runtime is not found.

```bash
npm i -g selenium-standalone
```

```bash
selenium-standalone install
```

```bash
selenium-standalone start
```

--------------------------------

### Install ts-node for Testplane TypeScript

Source: https://github.com/gemini-testing/testplane/blob/master/docs/typescript.md

Install the `ts-node` package as a development dependency to enable running Testplane tests written in TypeScript.

```bash
npm i -D ts-node
```

--------------------------------

### Configure Testplane with Chrome Devtools Protocol

Source: https://github.com/gemini-testing/testplane/blob/master/docs/quick-start.md

This JavaScript configuration file sets up Testplane to use the Chrome Devtools Protocol for browser automation. It defines test sets, specifies the files containing tests, and configures the 'chrome' browser with the 'devtools' automation protocol.

```javascript
module.exports = {
    sets: {
        desktop: {
            files: 'tests/desktop/**/*.testplane.js'
        }
    },

    browsers: {
        chrome: {
            automationProtocol: 'devtools',
            desiredCapabilities: {
                browserName: 'chrome'
            }
        }
    }
};
```

--------------------------------

### Configure Testplane with Webdriver Protocol

Source: https://github.com/gemini-testing/testplane/blob/master/docs/quick-start.md

This JavaScript configuration file sets up Testplane to use the Webdriver protocol for browser automation. It specifies the Grid URL, defines test sets, and configures the 'chrome' browser with the 'webdriver' automation protocol. This configuration is suitable for remote browser execution.

```javascript
module.exports = {
    gridUrl: 'http://localhost:4444/wd/hub',

    sets: {
        desktop: {
            files: 'tests/desktop/*.testplane.js'
        }
    },

    browsers: {
        chrome: {
            automationProtocol: 'webdriver', // default value
            desiredCapabilities: {
                browserName: 'chrome'
            }
        }
    }
};
```

--------------------------------

### AssertView: Full Example with Options

Source: https://github.com/gemini-testing/testplane/blob/master/docs/writing-tests.md

Demonstrates a comprehensive usage of the assertView command, including various optional parameters for fine-grained control over screenshot capture and comparison.

```javascript
it('some test', async ({ browser }) => {
    await browser.url('some/url');
    await browser.assertView(
        'plain', '.form',
        {
            ignoreElements: ['.link'],
            tolerance: 5,
            antialiasingTolerance: 4,
            allowViewportOverflow: true,
            captureElementFromTop: true,
            compositeImage: true,
        }
    );
});
```

--------------------------------

### Create a New Test Project with Testplane CLI

Source: https://github.com/gemini-testing/testplane/blob/master/CONTRIBUTING.md

Instructions for using the Testplane CLI to scaffold a new test project. This allows developers to test their changes in a realistic environment.

```bash
npm init testplane@latest testplane-test-project
```

--------------------------------

### Initialize New Testplane Project via CLI

Source: https://github.com/gemini-testing/testplane/blob/master/README.md

Sets up a new Testplane project using the command-line interface. This command generates the basic configuration and structure for your tests. An optional verbose flag can be used for more detailed setup options.

```shell
npm init testplane@latest new-testplane-project

```

```shell
npm init testplane@latest new-testplane-project -- --verbose

```

--------------------------------

### Install Project Dependencies

Source: https://github.com/gemini-testing/testplane/blob/master/examples/android-apps/README.md

Installs all the necessary Node.js dependencies for the project using npm ci, ensuring a clean and reliable installation.

```shell
npm ci
```

--------------------------------

### Subscribing to Testplane Events

Source: https://github.com/gemini-testing/testplane/blob/master/docs/programmatic-api.md

Provides an example of subscribing to Testplane events, such as the INIT event, allowing you to hook into the Testplane lifecycle.

```APIDOC
## Subscribing to Events

### Description
Access the Testplane events object to subscribe to various lifecycle events. This allows for custom logic execution at different stages of the test run.

### Method
`testplane.on(eventName, callback)`

### Endpoint
N/A (Instance method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
// Assuming 'testplane' is an initialized instance
testplane.on(testplane.events.INIT, async () => {
    console.info('INIT event is being processed...');
});
```

### Response
#### Success Response (200)
The callback function is executed when the specified event is triggered.

#### Response Example
```javascript
// Console output when INIT event occurs:
// INIT event is being processed...
```

### Note
For a comprehensive list of events, refer to the [Testplane Events](events.md) documentation.
```

--------------------------------

### Build and Watch Testplane Changes

Source: https://github.com/gemini-testing/testplane/blob/master/CONTRIBUTING.md

Commands to build the Testplane project or to continuously watch for file changes and rebuild automatically. Useful during active development.

```bash
npm run build
# or
npm run watch
```

--------------------------------

### Install Testplane in Existing Project (Bash)

Source: https://context7.com/gemini-testing/testplane/llms.txt

Command to install Testplane as a development dependency in an existing Node.js project. This command should be run within the project's root directory.

```bash
npm install -D testplane
```

--------------------------------

### Running Tests

Source: https://github.com/gemini-testing/testplane/blob/master/docs/programmatic-api.md

Details the 'run' method for starting the test execution process. It can run all configured tests or a specified subset.

```APIDOC
## Run Tests

### Description
Initiates the test execution. By default, it runs all tests defined in the configuration. You can also specify particular tests to run.

### Method
`testplane.run(options)`

### Endpoint
N/A (Instance method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **options** (Object) - Optional - An object specifying which tests to run.
  - **files** (Array<String>) - Optional - An array of file paths for specific tests to run.

### Request Example
```javascript
// Run all tests
testplane.run();

// Run specific tests
testplane.run({ files: ['tests/example.js'] });
```

### Response
#### Success Response (200)
Tests are executed. The method returns a Promise that resolves when the run is complete.

#### Response Example
```javascript
// Promise resolves upon completion
```
```

--------------------------------

### Save API Instance to executionContext.ctx in beforeEach Hook

Source: https://github.com/gemini-testing/testplane/blob/master/docs/typescript.md

Example of saving a custom API instance to `executionContext.ctx` within a `beforeEach` global hook. This makes the API instance readily available for subsequent test operations, after performing authentication.

```typescript
import type { TestFunctionCtx } from 'testplane';
import { Api } from './api';

beforeEach(async (this: TestFunctionCtx) => {
  // Assume this is some custom command you want to run before each test
  await this.browser.auth();

  // Assume after auth we have access to a cookie needed to make requests to API
  const sessionIdCookie = await this.getCookies(['Session_id']).then(cookies => cookies?.[0]?.value);
  const api = new Api(sessionIdCookie);

  // Now we want to make api available via executionContext.ctx
  this.api = api;
})
```

--------------------------------

### Run All Testplane Tests (Bash)

Source: https://context7.com/gemini-testing/testplane/llms.txt

Basic command to execute all Testplane tests defined in the configuration. Includes examples for running with specific options, targeting specific test paths, and using multiple reporters.

```bash
npx testplane

# Run with specific options
npx testplane --browsers chrome --grep "login" --update-refs

# Run tests from specific paths
npx testplane tests/auth/ tests/checkout/

# Run in headless mode with reporters
npx testplane --reporter html --reporter json

```

--------------------------------

### Handle CoreError in Testplane (Example)

Source: https://github.com/gemini-testing/testplane/blob/master/docs/programmatic-api.md

Provides an example of the error message associated with a CoreError in Testplane, which occurs when a browser fails to calibrate a blank page.

```text
Could not calibrate. This could be due to calibration page has failed to open properly
```

--------------------------------

### run

Source: https://github.com/gemini-testing/testplane/blob/master/docs/programmatic-api.md

Starts running tests. By default, it runs all tests defined in the configuration file, but it can also be configured to run specific tests.

```APIDOC
## run

### Description
Starts running tests. By default run all tests from the config. Can also run only the specified tests. Returns `true` if the test run succeeded, and `false` if it failed.

### Example
```js
// create testplane instance
const success = await testplane.run(testPaths, options);
```

### Parameters
#### testPaths `String[]|TestCollection` (optional)
Paths to tests relative to `process.cwd`. Also accepts test collection returned by `readTests`.

#### options `Object` (optional)
- **reporters** `String[]` (optional) – Test result reporters.
- **browsers** `String[]` (optional) – Browsers to run tests in.
- **sets** `String[]` (optional) – Sets to run tests in.
- **grep** `RegExp` (optional) – Pattern that defines which tests to run.
```

--------------------------------

### Basic Testplane Configuration File (JavaScript)

Source: https://context7.com/gemini-testing/testplane/llms.txt

Example of a basic Testplane configuration file (`.testplane.conf.js` or `testplane.config.ts`). It defines base URLs, browser configurations, test sets, plugins, and various timeouts and settings for test execution.

```javascript
// .testplane.conf.js or testplane.config.ts
module.exports = {
    baseUrl: 'https://example.com',
    gridUrl: 'http://localhost:4444/wd/hub',

    browsers: {
        chrome: {
            automationProtocol: 'webdriver',
            desiredCapabilities: {
                browserName: 'chrome',
                'goog:chromeOptions': {
                    args: ['--headless', '--disable-gpu']
                }
            },
            windowSize: '1920x1080',
            sessionsPerBrowser: 5,
            testsPerSession: 10,
            retry: 2,
            screenshotsDir: './screenshots',
            tolerance: 2.3,
            antialiasingTolerance: 4,
            compositeImage: true,
            screenshotDelay: 0
        },
        firefox: {
            desiredCapabilities: {
                browserName: 'firefox',
                'moz:firefoxOptions': {
                    args: ['-headless']
                }
            }
        }
    },

    sets: {
        desktop: {
            files: 'tests/**/*.testplane.{js,ts}',
            browsers: ['chrome', 'firefox']
        }
    },

    plugins: {
        'html-reporter/hermione': {
            enabled: true,
            path: 'testplane-report',
            defaultView: 'all'
        }
    },

    screenshotMode: 'fullpage',
    strictTestsOrder: false,
    httpTimeout: 30000,
    pageLoadTimeout: 20000,
    testTimeout: 90000,
    waitTimeout: 3000,
    resetCursor: true,
    takeScreenshotOnFails: {
        testFail: true,
        assertViewFail: false
    }
};

```

--------------------------------

### Access API Instance from executionContext.ctx in Custom Command

Source: https://github.com/gemini-testing/testplane/blob/master/docs/typescript.md

Demonstrates how to access a previously saved API instance from `executionContext.ctx` within a custom command. This avoids redundant setup and ensures consistent data access.

```typescript
// Assume we are implementing a custom command to get profile info
export async function getProfileInfo() {
    const api = this.executionContext.ctx.api;

    return api.getProfileInfo();
}
```

--------------------------------

### Launch Testplane GUI Mode

Source: https://github.com/gemini-testing/testplane/blob/master/README.md

Starts the Testplane graphical user interface (GUI) for running tests. The GUI mode allows for interactive test execution, debugging, and visual feedback during the testing process.

```shell
npx testplane gui

```

--------------------------------

### Testplane Test and Hook Arguments Example (JavaScript)

Source: https://github.com/gemini-testing/testplane/blob/master/docs/writing-tests.md

Demonstrates how to access browser client and current test information within Testplane's beforeEach, afterEach, and it callbacks. Also shows passing custom data via options.

```javascript
beforeEach(async ({ browser, currentTest }) => {
    await browser.url(`/foo/bar?baz=${currentTest.id}`);
});

afterEach(async ({ browser, currentTest }) => {
    // Do some post actions with browser
});

it('some test', async ({ browser, currentTest }) => {
    await browser.click('.some-button');

    // Do some actions and asserts
});

beforeEach(async (opts) => {
    opts.bar = 'bar';
});

it('some test', async ({ browser, bar }) => {
    await browser.url(`/foo/${bar}`);

    // Do some actions and asserts
});

beforeEach(async function() {
    await this.browser.url(`/foo/bar?baz=${this.currentTest.id}`);
});

afterEach(async function() {
    // Do some post actions with this.browser
});

it('some test', async function() {
    await this.browser.click('.some-button');

    // Do some actions and asserts
});
```

--------------------------------

### Link Local Testplane to Test Project

Source: https://github.com/gemini-testing/testplane/blob/master/CONTRIBUTING.md

Commands to link a locally developed Testplane repository to a separate test project. This enables seamless testing of local modifications in the test project.

```bash
cd testplane
npm link

cd testplane-test-project
npm link testplane
```

--------------------------------

### Integrate Dev Server with Testplane

Source: https://context7.com/gemini-testing/testplane/llms.txt

This JavaScript configuration enables integration with a development server for Testplane tests. It specifies the command to start the server, the port it runs on, options for logging server output, and a custom readiness probe to ensure the server is available before tests begin.

```javascript
module.exports = {
    devServer: {
        command: 'npm run dev',
        port: 3000,
        logs: true,
        readinessProbe: async () => {
            // Custom check to ensure server is ready
            const response = await fetch('http://localhost:3000/health');
            return response.ok;
        }
    },

    baseUrl: 'http://localhost:3000'
};
```

--------------------------------

### Run Local Linters and Tests

Source: https://github.com/gemini-testing/testplane/blob/master/CONTRIBUTING.md

Command to execute all linters and tests locally within the Testplane repository. This ensures code quality and test coverage before submitting changes.

```bash
npm test
```

--------------------------------

### Run Testplane Tests in GUI Mode (Bash)

Source: https://context7.com/gemini-testing/testplane/llms.txt

Command to launch Testplane in GUI mode, which provides an interactive interface for developing and debugging tests. Examples show running with specific browsers and test sets.

```bash
npx testplane gui

# GUI with specific browsers
npx testplane gui --browsers chrome --set desktop

```

--------------------------------

### Subscribe to INIT Event

Source: https://github.com/gemini-testing/testplane/blob/master/docs/events/init.md

This snippet demonstrates how to subscribe to the INIT event using the `testplane.on()` method. The handler can be asynchronous, ensuring tasks only start after the promise resolves. No specific data is passed to the handler.

```javascript
testplane.on(testplane.events.INIT, async () => {
    console.info('Processing INIT event…');
});
```

--------------------------------

### Run Testplane Tests

Source: https://github.com/gemini-testing/testplane/blob/master/docs/programmatic-api.md

Starts the execution of Testplane tests. It can run all tests defined in the configuration or a specified subset based on paths, options, reporters, browsers, sets, or a grep pattern. Returns a boolean indicating success or failure.

```javascript
const success = await testplane.run(testPaths, options);
```

--------------------------------

### Testplane Event Handling and Interception

Source: https://context7.com/gemini-testing/testplane/llms.txt

Provides a comprehensive example of subscribing to various Testplane events (INIT, RUNNER_START, SESSION_START, TEST_BEGIN, TEST_PASS, TEST_FAIL, RUNNER_END) and intercepting the `TEST_FAIL` event to transform failures into passes for known flaky issues. It also demonstrates checking overall test status.

```javascript
const Testplane = require('testplane');
const testplane = new Testplane('./.testplane.conf.js');

// Subscribe to events
testplane.on(testplane.events.INIT, async () => {
    console.log('Testplane initialized');
});

testplane.on(testplane.events.RUNNER_START, (runner) => {
    console.log('Test runner started');
});

testplane.on(testplane.events.SESSION_START, async (browser, { browserId, sessionId }) => {
    console.log(`Session started: ${browserId} (${sessionId})`);
    await browser.execute(() => {
        console.log('Injecting test data...');
    });
});

testplane.on(testplane.events.TEST_BEGIN, (test) => {
    console.log(`Starting test: ${test.fullTitle()}`);
});

testplane.on(testplane.events.TEST_PASS, (result) => {
    console.log(`✓ ${result.fullTitle()} (${result.duration}ms)`);
});

testplane.on(testplane.events.TEST_FAIL, (result) => {
    console.log(`✗ ${result.fullTitle()}`);
    console.log(`Error: ${result.err.message}`);

    // Access assert view results
    if (result.assertViewResults) {
        result.assertViewResults.forEach(assertResult => {
            if (assertResult.name === 'ImageDiffError') {
                console.log(`Visual diff in state: ${assertResult.stateName}`);
                console.log(`Diff ratio: ${assertResult.diffRatio}`);
            }
        });
    }
});

testplane.on(testplane.events.RUNNER_END, (stats) => {
    console.log('Test execution finished');
    console.log(`Total: ${stats.total}`);
    console.log(`Passed: ${stats.passed}`);
    console.log(`Failed: ${stats.failed}`);
    console.log(`Skipped: ${stats.skipped}`);
    console.log(`Retries: ${stats.retries}`);
});

// Intercept and transform events
testplane.intercept(testplane.events.TEST_FAIL, ({ event, data }) => {
    const test = data;

    // Check if error is a known flaky issue
    if (test.err.message.includes('Connection refused')) {
        console.log('Known flaky error, converting to pass');
        return {
            event: testplane.events.TEST_PASS,
            data: test
        };
    }

    // Let event proceed normally
    return { event, data };
});

// Check if tests failed
testplane.on(testplane.events.RUNNER_END, () => {
    if (testplane.isFailed()) {
        console.log('Some tests failed');
    } else {
        console.log('All tests passed');
    }
});

testplane.run();
```

--------------------------------

### Implement Testplane Dev Server Plugin (JavaScript)

Source: https://github.com/gemini-testing/testplane/blob/master/docs/events/usage-examples/starting-dev-server.md

This JavaScript code implements a Testplane plugin that automatically launches a development server. It listens for CLI and INIT events to manage the server's lifecycle and options. Dependencies include 'http' for server creation and a local './config' module. It accepts options to enable/disable the server and configure its behavior.

```javascript
const http = require('http');
const parseConfig = require('./config');

module.exports = (testplane, opts) => {
    const pluginConfig = parseConfig(opts);

    if (!pluginConfig.enabled || testplane.isWorker()) {
        // either the plugin is disabled, or we are in the worker context - leave
        return;
    }

    let program;

    testplane.on(testplane.events.CLI, (cli) => {
        // we need to save a reference to the commander instance (https://github.com/tj/commander.js),
        // to check for the option later
        program = cli;
        // add the --dev-server option to testplane,
        // so that the user can explicitly specify when to run the dev-server
        cli.option('--dev-server', 'run dev-server');
    });

    testplane.on(testplane.events.INIT, () => {
        // the dev server can be launched either by specifying the --dev-server option
        // when launching testplane, or in the plugin settings
        const devServer = program && program.devServer || pluginConfig.devServer;

        if (!devServer) {
            // if the dev server does not need to be launched, we leave
            return;
        }

        // content that the dev server gives out
        const content = '<h1>Hello, World!</h1>';

        // create a server and start listening on port 3000
        http
            .createServer((req, res) => res.end(content))
            .listen(3000);

        // at http://localhost:3000/index.html the following will be given out: <h1>Hello, World!</h1>
    });
};
```

--------------------------------

### Storybook Community and Resources

Source: https://github.com/gemini-testing/testplane/blob/master/examples/storybook-autoscreenshots/src/stories/Configure.mdx

Engage with the Storybook community, contribute to its development, and access learning resources. Find support, watch tutorials, and stay updated on the latest features. Links to GitHub, Discord, YouTube, and tutorials are provided.

```html
<div className="sb-section sb-socials">
    <div className="sb-section-item">
      <img src={Github} alt="Github logo" className="sb-explore-image"/>
      Join our contributors building the future of UI development.

      <a
        href="https://github.com/storybookjs/storybook"
        target="_blank"
      >Star on GitHub<RightArrow /></a>
    </div>
    <div className="sb-section-item">
      <img src={Discord} alt="Discord logo" className="sb-explore-image"/>
      <div>
        Get support and chat with frontend developers.

        <a
          href="https://discord.gg/storybook"
          target="_blank"
        >Join Discord server<RightArrow /></a>
      </div>
    </div>
    <div className="sb-section-item">
      <img src={Youtube} alt="Youtube logo" className="sb-explore-image"/>
      <div>
        Watch tutorials, feature previews and interviews.

        <a
          href="https://www.youtube.com/@chromaticui"
          target="_blank"
        >Watch on YouTube<RightArrow /></a>
      </div>
    </div>
    <div className="sb-section-item">
      <img src={Tutorials} alt="A book" className="sb-explore-image"/>
      <p>Follow guided walkthroughs on for key workflows.</p>

      <a
          href="https://storybook.js.org/tutorials/"
          target="_blank"
        >Discover tutorials<RightArrow /></a>
    </div>
</div>
```

--------------------------------

### Intercept and Translate Events in Testplane Plugins

Source: https://github.com/gemini-testing/testplane/blob/master/docs/events.md

Illustrates how to use the `testplane.intercept()` method to intercept events and translate them to other events. This is useful for modifying event behavior or routing events differently. The example shows how to intercept `TEST_FAIL` and translate it to `TEST_PENDING`, preventing the original handler from being called.

```javascript
module.exports = (testplane) => {
    testplane.intercept(testplane.events.TEST_FAIL, ({event, data: test}) => {
        test.skip({reason: 'intercepted failure'});

        return {event: testplane.events.TEST_PENDING, test};
    });

    testplane.on(testplane.events.TEST_FAIL, (test) => {
        // this event handler will never be called
    });

    testplane.on(testplane.evenst.TEST_PENDING, (test) => {
        // this event handler will always be called instead of 'TEST_FAIL' one
    });
};
```

--------------------------------

### Write Test for Dev Server Content (JavaScript)

Source: https://github.com/gemini-testing/testplane/blob/master/docs/events/usage-examples/starting-dev-server.md

This JavaScript test code uses Testplane and Chai to verify content served by the development server. It navigates to 'index.html' using the configured 'baseUrl' and asserts that the 'h1' element contains 'Hello, World!'. This test ensures the dev server is functioning correctly and serving the expected content.

```javascript
const { assert } = require('chai');

describe('example', async () => {
    it('should find hello world', async ({ browser }) => {
        // baseUrl, relative to which index.html is set,
        // specified in the Testplane config above
        await browser.url('index.html');

        const title = await browser.$('h1').getText();
        assert.equal(title, 'Hello, World!');
    });
});
```

--------------------------------

### Configure Testplane for Dev Server (JavaScript)

Source: https://github.com/gemini-testing/testplane/blob/master/docs/events/usage-examples/starting-dev-server.md

This JavaScript configuration file sets up Testplane to use a development server. It specifies the grid URL, the base URL for the dev server, and browser configurations. The 'testplane-dev-server' plugin is enabled, with the dev server initially disabled via the 'devServer: false' option.

```javascript
module.exports = {
    // tests will be run in the local browser,
    // see about selenium-standalone in the "Quick start" section
    gridUrl: 'http://localhost:4444/wd/hub',
    
    // specify the path to the dev server
    baseUrl: 'http://localhost:3000',

    browsers: {
        chrome: {
            desiredCapabilities: { browserName: 'chrome' }
        }
    },

    plugins: {
        // add our plugin to the list of plugins
        'testplane-dev-server': {
            enabled: true,
            // the dev server will not start by default
            devServer: false
        },
    }
};
```

--------------------------------

### Testplane Initialization and Running Tests

Source: https://context7.com/gemini-testing/testplane/llms.txt

This section details how to initialize a Testplane instance and run test suites programmatically. You can initialize Testplane with a configuration file or a configuration object and then execute all tests or specific subsets of tests.

```APIDOC
## Programmatic API: Testplane Initialization and Running Tests

### Description
Initializes a Testplane instance and demonstrates how to run test suites.

### Method
- Constructor: `new Testplane(config)`
- Run Tests: `testplane.run(filesOrGlobs?, options?): Promise<boolean>`

### Parameters
#### Constructor Parameters
- **config** (object | string) - Path to configuration file or configuration object.

#### `run()` Method Parameters
- **filesOrGlobs** (string[]) - Optional. An array of file paths or glob patterns to specify which tests to run.
- **options** (object) - Optional. Configuration options for the test run.
    - **browsers** (string[]) - List of browsers to run tests on.
    - **sets** (string[]) - List of test sets to run.
    - **grep** (RegExp) - Regular expression to filter tests by title.
    - **reporters** (string[]) - List of reporters to use.

### Request Example (Initialization)
```javascript
const Testplane = require('testplane');

// Initialize with config file path
const testplane = new Testplane('./.testplane.conf.js');

// Or with config object
const testplane = new Testplane({
    baseUrl: 'https://example.com',
    browsers: {
        chrome: {
            desiredCapabilities: {
                browserName: 'chrome'
            }
        }
    },
    sets: {
        all: {
            files: 'tests/**/*.testplane.js',
            browsers: ['chrome']
        }
    }
});
```

### Request Example (Running Tests)
```javascript
// Run all tests
async function runTests() {
    const success = await testplane.run();
    if (success) {
        console.log('All tests passed!');
        process.exit(0);
    } else {
        console.log('Some tests failed');
        process.exit(1);
    }
}

// Run specific tests
async function runSpecificTests() {
    const success = await testplane.run(
        ['tests/auth/', 'tests/checkout/'],
        {
            browsers: ['chrome', 'firefox'],
            sets: ['desktop'],
            grep: /login/,
            reporters: ['html', 'json']
        }
    );
    return success;
}

runTests().catch(err => {
    console.error('Test run failed:', err);
    process.exit(1);
});
```

### Response
- **success** (boolean) - Indicates whether all tests passed (`true`) or if there were failures (`false`).

### Response Example (Success)
```
All tests passed!
```

### Response Example (Failure)
```
Some tests failed
```
```

--------------------------------

### Install UiAutomator2 Driver for Appium

Source: https://github.com/gemini-testing/testplane/blob/master/examples/android-apps/README.md

Installs the UiAutomator2 driver, required for automating Android native and hybrid applications with Appium. This command is run after installing project dependencies.

```shell
./node_modules/.bin/appium driver install uiautomator2
```

--------------------------------

### Initialize and Run Testplane Tests Programmatically

Source: https://context7.com/gemini-testing/testplane/llms.txt

Demonstrates how to create and run a Testplane instance using its programmatic API. Shows initialization with a config file or object, running all tests, and running specific filtered tests.

```javascript
const Testplane = require('testplane');

// Initialize with config file path
const testplane = new Testplane('./.testplane.conf.js');

// Or with config object
const testplane = new Testplane({
    baseUrl: 'https://example.com',
    browsers: {
        chrome: {
            desiredCapabilities: {
                browserName: 'chrome'
            }
        }
    },
    sets: {
        all: {
            files: 'tests/**/*.testplane.js',
            browsers: ['chrome']
        }
    }
});

// Run all tests
async function runTests() {
    const success = await testplane.run();

    if (success) {
        console.log('All tests passed!');
        process.exit(0);
    } else {
        console.log('Some tests failed');
        process.exit(1);
    }
}

// Run specific tests
async function runSpecificTests() {
    const success = await testplane.run(
        ['tests/auth/', 'tests/checkout/'],
        {
            browsers: ['chrome', 'firefox'],
            sets: ['desktop'],
            grep: /login/,
            reporters: ['html', 'json']
        }
    );

    return success;
}

runTests().catch(err => {
    console.error('Test run failed:', err);
    process.exit(1);
});

```

--------------------------------

### Initializing Testplane

Source: https://github.com/gemini-testing/testplane/blob/master/docs/programmatic-api.md

Demonstrates how to initialize Testplane programmatically by requiring the module and creating an instance with a configuration object or path.

```APIDOC
## Initialize Testplane

### Description
Instantiate the Testplane API by requiring the 'testplane' module and creating a new instance, passing a configuration object or a path to a configuration file.

### Method
`new Testplane(config)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **config** (Object|String) - Required - Configuration object or path to the configuration file.

### Request Example
```javascript
const Testplane = require('testplane');
const testplane = new Testplane(config);
```

### Response
#### Success Response (200)
An instance of the Testplane API is returned.

#### Response Example
```javascript
// testplane instance
```
```

--------------------------------

### Initialize Testplane Programmatically (JavaScript)

Source: https://github.com/gemini-testing/testplane/blob/master/docs/programmatic-api.md

Demonstrates how to require the 'testplane' module and create an instance of Testplane with a configuration object or path. This is the first step to using the programmatic API.

```javascript
const Testplane = require('testplane');
const testplane = new Testplane(config);
```

--------------------------------

### readTests

Source: https://github.com/gemini-testing/testplane/blob/master/docs/programmatic-api.md

Starts reading tests from the configuration. Can read all tests or only specified ones. Returns a promise that resolves to a TestCollection instance.

```APIDOC
## POST /gemini-testing/testplane/readTests

### Description
Starts reading tests. By default, reads all tests from the config. Can also read only the specified tests. Returns a promise which resolves to an instance of [TestCollection](#test-collection) initialized by parsed tests.

### Method
POST

### Endpoint
/gemini-testing/testplane/readTests

### Parameters
#### Query Parameters
- **testPaths** (String[]) - Required - Paths to tests relative to `process.cwd`.
- **options** (Object) - Optional
    - **browsers** (String[]) - Optional - Read tests only for the specified browsers.
    - **silent** (Boolean) - Optional - Flag to disable events emitting while reading tests; default is `false`.
    - **ignore** (String|Glob|Array<String|Glob>) - Optional - Patterns to exclude paths from the test search.
    - **sets** (String[]) - Optional - Sets to run tests in.
    - **grep** (RegExp) - Optional - Pattern that defines which tests to run.
    - **replMode** ({enabled: boolean; beforeTest: boolean; onFail: boolean;}) - Optional - Test development mode using REPL. When reading the tests, it checks that only one test is running in one browser.
        - **enabled** (boolean) - Optional - Enable REPL mode.
        - **beforeTest** (boolean) - Optional - Enable REPL before each test.
        - **onFail** (boolean) - Optional - Enable REPL on test failure.
    - **runnableOpts** (Object) - Optional
        - **saveLocations** (Boolean) - Optional - Flag to save `location` (`line` and `column`) to suites and tests. Allows to determine where the suite or test is declared in the file.

### Request Example
```json
{
  "testPaths": ["path/to/tests"],
  "options": {
    "browsers": ["chrome"],
    "silent": true
  }
}
```

### Response
#### Success Response (200)
- **TestCollection** (Object) - An instance of TestCollection initialized by parsed tests.

#### Response Example
```json
{
  "_collection": {
    "tests": [...]
  }
}
```
```

--------------------------------

### Run Testplane Tests

Source: https://github.com/gemini-testing/testplane/blob/master/examples/android-apps/README.md

Executes the Testplane test suite. This command should be run after Appium server is active and all dependencies are installed.

```shell
npx testplane
```

--------------------------------

### Handle CancelledError in Testplane (Example)

Source: https://github.com/gemini-testing/testplane/blob/master/docs/programmatic-api.md

Shows the error message for a CancelledError in Testplane, which is returned when the halt command terminates a test run abnormally.

```text
Browser request was cancelled
```

--------------------------------

### SESSION_START Event Subscription

Source: https://github.com/gemini-testing/testplane/blob/master/docs/events/session-start.md

The SESSION_START event is triggered after the browser session is initialized. The event handler can be asynchronous, and tests will only start executing after the returned Promise is resolved.

```APIDOC
## POST /events/SESSION_START

### Description
Subscribes to the SESSION_START event, which fires after a browser session is initialized. Allows for asynchronous event handling before test execution begins.

### Method
SUBSCRIBE (Conceptual)

### Endpoint
N/A (Event-based subscription within Testplane)

### Parameters
#### Handler Parameters
- **browser** (WebdriverIO instance) - The WebdriverIO instance for the current browser session.
- **{ browserId, sessionId }** (object) - An object containing:
    - **browserId** (string) - The name of the browser.
    - **sessionId** (string) - The ID of the browser session.

### Request Example
```javascript
testplane.on(testplane.events.SESSION_START, async (browser, { browserId, sessionId }) => {
    console.info('SESSION_START event is being processed…');
});
```

### Response
#### Success Response (Event Triggered)
- **void** - No direct response, but the handler function is executed.

#### Response Example
(N/A - Event-driven)

### Error Handling
- If the handler function throws an error, it will be logged by Testplane.
```

--------------------------------

### Configure tsconfig.json for Testplane Types

Source: https://github.com/gemini-testing/testplane/blob/master/docs/typescript.md

Update your `tsconfig.json` file to include 'testplane' in the `types` compiler option. This ensures TypeScript recognizes Testplane-specific types.

```json
// tsconfig.json
{
    // other tsconfig options
    "compilerOptions": {
        // other compiler options
        "types": [
            // other types
            "testplane",
        ]
    }
}
```

--------------------------------

### Run Appium Server

Source: https://github.com/gemini-testing/testplane/blob/master/examples/android-apps/README.md

Starts the Appium server on port 4444 with relaxed security settings. This server is necessary to execute tests on Android devices or emulators.

```shell
npx appium -p 4444 --relaxed-security
```

--------------------------------

### Storybook Addon Integrations

Source: https://github.com/gemini-testing/testplane/blob/master/examples/storybook-autoscreenshots/src/stories/Configure.mdx

Enhance Storybook's functionality by integrating various tools and workflows. Storybook addons allow for extending capabilities and connecting with your existing development ecosystem. Discover available addons through the provided link.

```html
<div className='sb-addon'>
  <div className='sb-addon-text'>
    <h4>Addons</h4>
    <p className="sb-section-item-paragraph">Integrate your tools with Storybook to connect workflows.</p>
    <a
        href="https://storybook.js.org/addons/"
        target="_blank"
      >Discover all addons<RightArrow /></a>
  </div>
  <div className='sb-addon-img'>
    <img src={AddonLibrary} alt="Integrate your tools with Storybook to connect workflows." />
  </div>
</div>
```

--------------------------------

### Gemini Testing Testplane CSS Styles

Source: https://github.com/gemini-testing/testplane/blob/master/examples/storybook-autoscreenshots/src/stories/Configure.mdx

Contains various CSS rules for styling components within the Gemini Testing Testplane. Includes styles for .sb-addon, .sb-addon-text, .sb-addon-img, and responsive adjustments via media queries.

```css
.sb-addon {
    border: 1px solid rgba(0, 0, 0, 0.05);
    background: #EEF3F8;
    height: 180px;
    margin-bottom: 48px;
    overflow: hidden;
  }

  .sb-addon-text {
    padding-left: 48px;
    max-width: 240px;
  }

  .sb-addon-text h4 {
    padding-top: 0px;
  }

  .sb-addon-img {
    position: absolute;
    left: 345px;
    top: 0;
    height: 100%;
    width: 200%;
    overflow: hidden;
  }

  .sb-addon-img img {
    width: 650px;
    transform: rotate(-15deg);
    margin-left: 40px;
    margin-top: -72px;
    box-shadow: 0 0 1px rgba(255, 255, 255, 0);
    backface-visibility: hidden;
  }

  @media screen and (max-width: 800px) {
    .sb-addon-img {
      left: 300px;
    }
  }

  @media screen and (max-width: 600px) {
    .sb-section {
      flex-direction: column;
    }

    .sb-features-grid {
      grid-template-columns: repeat(1, 1fr);
    }

    .sb-socials {
      grid-template-columns: repeat(2, 1fr);
    }

    .sb-addon {
      height: 280px;
      align-items: flex-start;
      padding-top: 32px;
      overflow: hidden;
    }

    .sb-addon-text {
      padding-left: 24px;
    }

    .sb-addon-img {
      right: 0;
      left: 0;
      top: 130px;
      bottom: 0;
      overflow: hidden;
      height: auto;
      width: 124%;
    }

    .sb-addon-img img {
      width: 1200px;
      transform: rotate(-12deg);
      margin-left: 0;
      margin-top: 48px;
      margin-bottom: -40px;
      margin-left: -24px;
    }
  }
```

--------------------------------

### Handle ClientBridgeError in Testplane (Example)

Source: https://github.com/gemini-testing/testplane/blob/master/docs/programmatic-api.md

Displays the error message for a ClientBridgeError in Testplane, indicating a failure in injecting JavaScript code into the browser via WebDriverIO's execute command.

```text
Unable to inject client script
```

--------------------------------

### Testplane Event Interception: Ignoring Events

Source: https://github.com/gemini-testing/testplane/blob/master/docs/events.md

Demonstrates how to use an interceptor to completely ignore an event by returning an empty object. This prevents the event from being processed by any other listeners, effectively silencing it.

```javascript
module.exports = (testplane) => {
    testplane.intercept(testplane.events.TEST_FAIL, ({event, data}) => {
        return {};
    });

    testplane.on(testplane.events.TEST_FAIL, (test) => {
        // this event handler will NEVER be called because interceptor ignores it
    });
};
```

--------------------------------

### OpenAndWait API

Source: https://github.com/gemini-testing/testplane/blob/master/docs/writing-tests.md

The `openAndWait` command navigates to a specified URL and waits until the page is considered loaded based on a combination of factors, including element presence, network activity, and custom predicates.

```APIDOC
## POST /gemini-testing/testplane/openAndWait

### Description
Opens a page and waits until it loads based on specified criteria.

### Method
POST

### Endpoint
/gemini-testing/testplane/openAndWait

### Parameters
#### Request Body
- **url** (String) - Required - The URL of the page to open.
- **waitOpts** (Object) - Optional - Options to configure the waiting behavior.
    - **selector** (String|String[]) - Optional - Selector(s) for elements that should exist on the page.
    - **predicate** (() => Promise<bool> | bool) - Optional - A function that returns true when the page is considered loaded. Executed in the browser context.
    - **waitNetworkIdle** (Boolean) - Optional - Waits until all network requests are done. `true` by default. Only works in chrome browser or via CDP.
    - **waitNetworkIdleTimeout** (Number) - Optional - Time (ms) after network requests are resolved to consider network idle. 500 by default.
    - **failOnNetworkError** (Boolean) - Optional - If `true`, throws an error on network request failures. `true` by default. Only works in chrome browser or via CDP.
    - **shouldThrowError** ((match) => Boolean) - Optional - Predicate to determine if a network error is critical for page load.
    - **ignoreNetworkErrorsPatterns** (Array<String | RegExp>) - Optional - Array of URL patterns to ignore network request errors.
    - **timeout** (Number) - Optional - Page load timeout in milliseconds.

### Request Example
```javascript
it('some test', async ({browser}) => {
    await browser.openAndWait('some/url', {
        selector: ['.some', '.selector'],
        predicate: () => document.isReady,
        ignoreNetworkErrorsPatterns: ['https://mc.yandex.ru'],
        waitNetworkIdle: true,
        waitNetworkIdleTimeout: 500,
        failOnNetworkError: true,
        timeout: 20000,
    });
});
```

### Response
#### Success Response (200)
- **status** (String) - Indicates the success of the operation.

#### Response Example
```json
{
  "status": "Page loaded successfully"
}
```
```

--------------------------------

### Basic Test Structure with Testplane

Source: https://context7.com/gemini-testing/testplane/llms.txt

Demonstrates the fundamental structure of a Testplane test suite using `describe` and `it` blocks. It covers successful login and handling invalid credentials, interacting with UI elements, and asserting their states. Assumes a web application with login functionality and corresponding selectors.

```typescript
describe('Authentication', () => {
    it('should login successfully', async ({ browser }) => {
        await browser.url('/login');

        const emailInput = await browser.$('#email');
        const passwordInput = await browser.$('#password');
        const submitButton = await browser.$('button[type="submit"]');

        await emailInput.setValue('user@example.com');
        await passwordInput.setValue('password123');
        await submitButton.click();

        const dashboard = await browser.$('.dashboard');
        await expect(dashboard).toBeDisplayed();

        const welcomeMessage = await browser.$('.welcome');
        await expect(welcomeMessage).toHaveText('Welcome back!');
    });

    it('should show error for invalid credentials', async ({ browser }) => {
        await browser.url('/login');

        await browser.$('#email').setValue('invalid@example.com');
        await browser.$('#password').setValue('wrong');
        await browser.$('button[type="submit"]').click();

        const errorMsg = await browser.$('.error-message');
        await expect(errorMsg).toHaveTextContaining('Invalid credentials');
    });
});
```

--------------------------------

### Handle HeightViewportError in Testplane (Example)

Source: https://github.com/gemini-testing/testplane/blob/master/docs/programmatic-api.md

Presents the error message for a HeightViewportError in Testplane, which occurs when attempting to screenshot an area that extends beyond the viewport. The message includes suggestions for configuration adjustments.

```text
Can not capture the specified region of the viewport.
The region bottom bound is outside of the viewport height.
Alternatively, you can test such cases by setting "true" value to option "compositeImage" in the config file
or setting "false" to "compositeImage" and "true" to option "allowViewportOverflow" in "assertView" command.
Element position: <cropArea.left>, <cropArea.top>; size: <cropArea.width>, <cropArea.height>.
Viewport size: <viewport.width>, <viewport.height>.
```

--------------------------------

### Using Test Hooks (beforeEach, afterEach) in Testplane

Source: https://context7.com/gemini-testing/testplane/llms.txt

Demonstrates the use of Testplane's test hooks, specifically `beforeEach` and `afterEach`. The `beforeEach` hook is used to set up the test environment by clearing session data and logging in before each test. The `afterEach` hook includes logic to save a screenshot if a test fails. Assumes login and product pages with relevant selectors.

```typescript
describe('Shopping cart', () => {
    beforeEach(async ({ browser }) => {
        // Clear cookies and storage before each test
        await browser.url('/');
        await browser.clearSession();

        // Login
        await browser.url('/login');
        await browser.$('#email').setValue('test@example.com');
        await browser.$('#password').setValue('test123');
        await browser.$('button[type="submit"]').click();
        await browser.waitForUrl('**/dashboard', { timeout: 5000 });
    });

    afterEach(async ({ browser }) => {
        // Take screenshot on failure
        if (browser.testplaneCtx?.assertViewResults?.hasFails()) {
            await browser.saveScreenshot('./screenshots/failure.png');
        }
    });

    it('should add item to cart', async ({ browser }) => {
        await browser.url('/products');
        await browser.$('.product-item:first-child .add-to-cart').click();

        const cartCount = await browser.$('.cart-badge');
        await expect(cartCount).toHaveText('1');
    });
});
```