Octomind

https://octomind.dev/docs/
Admin
Octomind is an AI-powered end-to-end testing platform that uses natural language prompts to...
Tokens:75,141
Snippets:864
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Octomind CLI

Source: https://octomind.dev/docs/run-tests/execution-local

Install the Octomind CLI globally using npm. Alternatively, use npx to run it directly without installation.

```bash
npm i -g @octomind/octomind
```

```bash
npx @octomind/octomind
```

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

### Install Dependencies

Source: https://octomind.dev/docs/cli/commands

Use this command to install project dependencies after cloning the repository. It is recommended to run this in your project's root directory.

```bash
pnpm install
```

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

### Start Demo App with Docker Compose

Source: https://octomind.dev/docs/guides/long-running

Start the demo application, which includes Flask, Celery, and a private location worker, using Docker Compose. This sets up the environment for testing long-running tasks.

```bash
docker-compose up --build
```

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

### Jenkinsfile Example

Source: https://octomind.dev/docs/integrations/quickstart-Jenkins

This is an example Jenkinsfile that can be used to integrate Octomind into your pipeline. It requires the AUTOMAGICALLY_TOKEN to be configured as a secret in Jenkins.

```groovy
pipeline {
    agent any
    stages {
        stage('Octomind') {
            steps {
                script {
                    // Replace with your actual Octomind API token ID
                    def octomindToken = credentials('AUTOMAGICALLY_TOKEN')
                    // Replace with your actual test target ID
                    def testTargetId = 'YOUR_TEST_TARGET_ID'

                    // Example: Trigger Octomind analysis
                    sh "octomind-cli analyze --token=\"${octomindToken}\" --target-id=${testTargetId}"
                }
            }
        }
    }
}
```

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

### Global Installation of Octomind CLI

Source: https://octomind.dev/docs/cli/installation

Install the Octomind CLI globally using npm. This is the recommended method for making the 'octomind' command available system-wide.

```bash
npm install -g @octomind/octomind
```

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

### Example Client for Hosted MCP Server

Source: https://octomind.dev/docs/mcp/hosted-mcp

Connect to the hosted MCP server using the StreamableHTTPClientTransport. Ensure the '@modelcontextprotocol/client' package is installed and the API_KEY environment variable is set. The 'x-session-id' header is recommended for sticky session routing.

```javascript
const serverUrl = "https://mcp.app.octomind.dev/mcp";
const apiKey = process.env.API_KEY;

console.log("Testing MCP server at:", serverUrl);
try {
  const transport = new StreamableHTTPClientTransport(new URL(serverUrl), {
    requestInit: {
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "x-session-id": "unique-session-id", // Optional, but recommended for sticky session routing
      },
    },
  });
  const client = new Client(
    {
      name: "test-client",
      version: "1.0.0",
    },
    {
      capabilities: {},
    },
  );
  console.log("Client created successfully!");

  await client.connect(transport);
  console.log("✅ Connected successfully!");

  console.log("Server capabilities:", client.getServerCapabilities());
  console.log("Server version:", client.getServerVersion());
  const capabilities = client.getServerCapabilities();
  // Test basic capabilities
  const tools = await client.listTools();
  console.log(
    "🔧 Available tools:",
    tools.tools.map((t) => t.name),
  );
} catch (error) {
  console.error("❌ Error connecting to MCP server:", error);
}
```

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

### Initialize Octomind CLI

Source: https://octomind.dev/docs/run-tests/execution-local

Initialize the Octomind CLI by setting up your API key. This is a one-time setup step.

```bash
octomind init
```

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

### Advanced Installation for Dependency Conflicts

Source: https://octomind.dev/docs/cli/installation

Install the Octomind CLI in a custom location to avoid global dependency conflicts. This involves creating a directory, installing the package, and then creating an alias or a symbolic link.

```bash
mkdir -p ~/.local/packages
cd ~/.local/packages
npm install @octomind/octomind@latest
# either create an alias
alias octomind="node ~/.local/packages/node_modules/@octomind/octomind/dist/index.js"
# or create a symlink
sudo ln -s ~/.local/packages/node_modules/@octomind/octomind/dist/index.js /usr/local/bin/octomind
```

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

### Example Initialization Commands

Source: https://octomind.dev/docs/cli/installation

Demonstrates how to initialize the Octomind CLI with an API key, with both API key and test target ID, and how to force overwrite existing configurations.

```bash
# Initialize with API key
octomind init --api-key your-api-key-here

# Initialize with API key and test target ID
octomind init --api-key your-api-key-here --test-target-id your-test-target-id

# Force overwrite existing configuration
octomind init --force
```

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

### Execute Preparation Phase for Demo App

Source: https://octomind.dev/docs/guides/long-running

Trigger the preparation phase for the demo application to start a background task. Replace <demo-app-id> with the actual ID of the demo app.

```bash
octomind execute --test-target-id <demo-app-id> --tags preparation
```

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

### Example Static User-Agent String

Source: https://octomind.dev/docs/advanced/octomind-bot

This is an example of a static user-agent string used by the Octomind bot to identify itself during web requests. It helps maintain a consistent client identity.

```plaintext
octomind Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.6312.4 Safari/537.36
```

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

### Update Octomind CLI (Advanced Installation)

Source: https://octomind.dev/docs/cli/installation

Update the Octomind CLI when installed using the advanced method. Navigate to the custom installation directory and install the latest version.

```bash
cd ~/.local/packages
npm install @octomind/octomind@latest
```

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

### Example JSON Output

Source: https://octomind.dev/docs/cli/commands

This is an example of the raw JSON output you can receive by using the --json flag with CLI commands. It details test report information including status and individual test results.

```json
{
  "id": "826c15af-644b-4b28-89b4-f50ff34e46b7",
  "testTargetId": "3435918b-3d29-4ebd-8c68-9a540532f45a",
  "status": "PASSED",
  "executionUrl": "https://example.com",
  "testResults": [
    {
      "id": "abc-123-456",
      "testTargetId": "3435918b-3d29-4ebd-8c68-9a540532f45a",
      "testCaseId": "test-1",
      "status": "PASSED",
      "traceUrl": "https://storage.googleapis.com/automagically-traces/abc-123-trace.zip"
    },
    {
      "id": "def-456-789",
      "testTargetId": "3435918b-3d29-4ebd-8c68-9a540532f45a",
      "testCaseId": "test-2",
      "status": "PASSED",
      "traceUrl": "https://storage.googleapis.com/automagically-traces/def-456-trace.zip"
    }
  ]
}
```

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

### Setup CI GitHub Action

Source: https://octomind.dev/docs/integrations/quickstart-GitHub

Include this GitHub Action in your CI/CD pipeline for pull requests. Ensure it's placed after your deployment step to link Octomind to a publicly accessible URL.

```yaml
- uses: OctoMind-dev/automagically-action-execute@v2
  with:
    url: <publicly accessible url to your deployment>
    token: ${{ secrets.OCTOMIND_API_KEY }}
    testTargetId: <your testTargetId from your octomind project>
    blocking: false
```

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

### Detailed Prompt Example

Source: https://octomind.dev/docs/guides/prompt-debugging

A more effective prompt that provides specific, actionable steps for the AI agent to follow, increasing the likelihood of successful test case generation.

```plaintext
1. Click on the cart icon.
2. Click on the 'CHECKOUT' button.
3. Verify the page title contains 'Checkout'
```

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

### Install Autocompletion for Octomind CLI

Source: https://octomind.dev/docs/cli/installation

Enable command autocompletion for the Octomind CLI on macOS and Linux (bash, zsh, fish). This requires a global installation and an initialized configuration.

```bash
npx @octomind/octomind install-completion
```

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

### Basic Prompt Example

Source: https://octomind.dev/docs/guides/prompt-debugging

A simple prompt that may lead to incomplete test cases. It lacks specific instructions for the checkout flow.

```plaintext
Navigate to the cart page and start checkout
```

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

### Run Octomind CLI with npx

Source: https://octomind.dev/docs/cli/installation

Execute the Octomind CLI without a global installation using npx. This is useful for one-off commands or quick testing.

```bash
npx @octomind/octomind -h
```

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

### Configure Static User Agent with Playwright

Source: https://octomind.dev/docs/advanced/octomind-bot

Set a static user-agent string for all requests to ensure a consistent bot signature. This example uses Playwright to launch a browser with a custom user agent.

```javascript
const { chromium } = require("playwright");

(async () => {
  const browser = await chromium.launch();
  const context = await browser.newContext({
    userAgent:
      "Mozilla/5.0 (Windows NT 10.0; Win64; x64; octomind/1.0.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.6312.4 Safari/537.36",
  });
  const page = await context.newPage();
  await page.goto("https://example.com");
  await browser.close();
})();
```

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

### Uninstall Autocompletion for Octomind CLI

Source: https://octomind.dev/docs/cli/installation

Disable command autocompletion for the Octomind CLI. This command removes the autocompletion setup previously installed.

```bash
npx @octomind/octomind uninstall-completion
```

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

### Debugtopus Shell Script for Local Testing

Source: https://octomind.dev/docs/run-tests/execution-local

This shell script is used to install and start Debugtopus for local test execution. Ensure you adjust the URL to your locally running application.

```bash
#!/bin/bash

# Install Debugtopus
npx @octomind/debugtopus install

# Start Debugtopus with your application URL
# Replace http://localhost:3000 with your application's URL
npx @octomind/debugtopus start --url http://localhost:3000
```

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

### Build CLI from Source

Source: https://octomind.dev/docs/cli/commands

Run this command to build the CLI from the source code. This is typically done after making changes to the source or before deploying.

```bash
pnpm run build
```

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

### Update Octomind CLI (Global Installation)

Source: https://octomind.dev/docs/cli/installation

Update the globally installed Octomind CLI to the latest version using npm.

```bash
npm update -g @octomind/octomind
```

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

### Run Preparation Phase Tests

Source: https://octomind.dev/docs/guides/long-running

Execute tests tagged with 'preparation' to initiate long-running backend tasks. Replace <your_test_target_id> with your actual test target ID.

```bash
octomind execute --test-target-id <your_test_target_id> --tags preparation
```

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

### Initialize Octomind CLI Configuration

Source: https://octomind.dev/docs/cli/installation

Initialize the Octomind CLI by setting up your API key and optionally a test target ID. This configuration avoids needing to pass these parameters for subsequent commands. Use --force to overwrite existing configuration.

```bash
octomind init \
  [--api-key <key>] \
  [--test-target-id <id>] \
  [--force]
```

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

### List Environments with Octomind CLI

Source: https://octomind.dev/docs/cli/commands

List all available environments for the configured test target. Use the --json flag for raw JSON output.

```bash
list-environments
```

```bash
list-environments --json
```

```bash
list-environments -t <test-target-id>
```

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

### test-case

Source: https://octomind.dev/docs/cli/commands

Get details of a specific test case.

```APIDOC
## test-case

### Description
Get details of a specific test case.

### Usage
`test-case [options]`

### Options
#### Query Parameters
- `-j, --json` (boolean) - Optional - Output raw JSON response
- `-c, --test-case-id <id>` (string) - Required - Test case ID
- `-t, --test-target-id [id]` (string) - Optional - Test target ID, if not provided will use the test target id from the config
```

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

### Create Environment with Octomind CLI

Source: https://octomind.dev/docs/cli/commands

Create a new environment using the Octomind CLI. This command requires specific options to be provided.

```bash
create-environment [options]
```

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

### code

Source: https://octomind.dev/docs/cli/commands

Get code of a specific test case.

```APIDOC
## code

### Description
Get code of a specific test case.

### Usage
`code [options]`

### Options
#### Query Parameters
- `-j, --json` (boolean) - Optional - Output raw JSON response
- `-c, --test-case-id <id>` (string) - Required - Test case ID
- `-u, --url <url>` (string) - Required - URL to execute the test case against
- `-e, --environment-id [id]` (string) - Optional - Environment ID
- `-t, --test-target-id [id]` (string) - Optional - Test target ID, if not provided will use the test target id from the config
```

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

### Get Test Plan by ID

Source: https://octomind.dev/docs/api-reference/test-plans/get-test-plan-by-id

Retrieves a specific test plan by its unique identifier.

```APIDOC
## GET /test-plans/{id}

### Description
Retrieves a specific test plan using its ID.

### Method
GET

### Endpoint
/test-plans/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the test plan to retrieve.

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the test plan.
- **createdAt** (string) - Timestamp when the test plan was created.
- **updatedAt** (string) - Timestamp when the test plan was last updated.
- **status** (string) - Current status of the test plan.
- **testTargetId** (string) - Identifier for the target of the test plan.
- **context** (object) - Contextual information for the test plan.

#### Error Response (404)
- Indicates that the test plan with the specified ID was not found.
```

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

### Retrieve code for a test case

Source: https://octomind.dev/docs/api-reference/test-cases/retrieve-code-for-a-test-case

Get the code representation of a specific test case.

```APIDOC
## GET /apiKey/v3/test-targets/{testTargetId}/test-cases/{testCaseId}/code

### Description
Get the code representation of a specific test case.

### Method
GET

### Endpoint
/apiKey/v3/test-targets/{testTargetId}/test-cases/{testCaseId}/code

### Parameters
#### Path Parameters
- **testTargetId** (string) - Required - The ID of the test target
- **testCaseId** (string) - Required - The ID of the test case

#### Query Parameters
- **executionUrl** (string) - Required - URL of the app to test
- **environmentId** (string) - Optional - Optional ID of the environment to use

### Responses
#### Success Response (200)
- **testCode** (string) - The code representation of the test case

#### Error Response (400)
Invalid request parameters

#### Error Response (401)
Unauthorized - Invalid or missing API key

#### Error Response (404)
Test target, test case, or test code not found
```

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

### Retrieve All Test Targets

Source: https://octomind.dev/docs/api-reference/test-targets/retrieve-all-test-targets

Gets a list of test targets. Requires an API key for authentication.

```APIDOC
## GET /apiKey/v3/test-targets

### Description
Gets a list of test targets.

### Method
GET

### Endpoint
/apiKey/v3/test-targets

### Parameters
#### Query Parameters
None

#### Request Body
None

### Responses
#### Success Response (200)
- **TestTargetsResponse** (array) - A list of test targets.

#### Error Responses
- **401** - Invalid or missing API key
- **500** - Internal server error

### Security
- ApiKeyAuth
```

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

### Octomind CLI Workflow Example

Source: https://octomind.dev/docs/dev-mode/commands

A typical workflow combining Octomind CLI commands with Git for managing test cases. This includes pulling tests, editing them visually, executing locally, and committing changes.

```bash
# 1. Initial setup - pull tests from Octomind
octomind pull

# 2. Edit a test case visually
octomind edit-test-case --file-path .octomind/checkout-flow.yaml

# 3. Test your changes locally
octomind execute-local --url https://localhost:3000

# 4. Commit your changes
git add .octomind/
git commit -m "Update checkout flow test"

# 5. Push to your repository
git push origin feature/update-checkout-test

# 6. After PR merge, CI/CD automatically pushes to Octomind
# (via GitHub Action in your workflow)

```
Tokens:
Raw