@testdriverai/agent 7.8.0-test.38

package/docs/v6/importing/gherkin.mdx

@@ -0,0 +1,143 @@
+---
+title: "Gherkin"
+sidebarTitle: "Gherkin"
+description: "Convert Gherkin scenarios to TestDriver prompts"
+icon: "file-code"
+---
+
+This guide explains how to convert **Gherkin scenarios** into **TestDriver prompts** for use in your testing workflows. By following this process, you can easily adapt existing Gherkin test cases into a format compatible with TestDriver.
+
+---
+
+## What's Gherkin?
+
+Gherkin is a plain-text language used to describe test scenarios in a human-readable format. It uses keywords like `Given`, `When`, `Then`, and `And` to define steps in a test.
+
+### Example Gherkin scenario:
+
+```gherkin
+Scenario: Successful login
+  Given the user is on the login page
+  When the user enters valid credentials
+  And clicks the "Log In" button
+  Then the user should see the dashboard
+```
+
+---
+
+## What are TestDriver prompts?
+
+TestDriver prompts are high-level instructions that describe what the AI should do. They're written in plain text and focus on user actions or expected outcomes.
+
+### Example prompts:
+
+```yaml
+- prompt: the user is on the login page
+- prompt: the user enters valid credentials
+- prompt: clicks the "Log In" button
+- prompt: the user should see the dashboard
+```
+
+---
+
+## Steps to convert Gherkin to TestDriver prompts
+
+### Step 1: Understand the mapping
+
+| **Gherkin Keyword** | **TestDriver Prompt**                      |
+| ------------------- | ------------------------------------------ |
+| `Given`             | Describes the initial state or setup.      |
+| `When`              | Describes the user action.                 |
+| `Then`              | Describes the expected outcome or result.  |
+| `And`               | Adds additional steps to the same context. |
+
+---
+
+### Step 2: Extract steps from Gherkin
+
+Take each step from the Gherkin scenario and rewrite it as a plain-text prompt. Remove the `Given`, `When`, `Then`, and `And` keywords, and focus on the action or expectation.
+
+#### Example:
+
+| **Gherkin Step**                         | **TestDriver Prompt**               |
+| ---------------------------------------- | ----------------------------------- |
+| `Given the user is on the login page`    | `the user is on the login page`     |
+| `When the user enters valid credentials` | `the user enters valid credentials` |
+| `And clicks the "Log In" button`         | `clicks the "Log In" button`        |
+| `Then the user should see the dashboard` | `the user should see the dashboard` |
+
+---
+
+### Step 3: Write the prompts in YAML format
+
+Combine the extracted prompts into a YAML file. Each step should be written as a `prompt` entry.
+
+#### Example YAML:
+
+```yaml
+- prompt: the user is on the login page
+- prompt: the user enters valid credentials
+- prompt: clicks the "Log In" button
+- prompt: the user should see the dashboard
+```
+
+---
+
+### Step 4: Save the YAML file
+
+1. Save the YAML content to a file (for example, `login_test.yaml`).
+2. Ensure the file is stored in the appropriate directory for your TestDriver project (for example, `testdriver/`).
+
+---
+
+### Step 5: Run the test with TestDriver
+
+Use the TestDriver CLI to execute the test.
+
+#### Command:
+
+```bash
+npx testdriverai@latest run login_test.yaml
+```
+
+---
+
+## Example: Full conversion workflow
+
+### Input Gherkin scenario:
+
+```gherkin
+Scenario: Add a product to the cart
+  Given the user is on the product page
+  When the user clicks "Add to Cart"
+  And confirms the action
+  Then the product should appear in the cart
+```
+
+### Converted YAML:
+
+```yaml
+- prompt: the user is on the product page
+- prompt: the user clicks "Add to Cart"
+- prompt: confirms the action
+- prompt: the product should appear in the cart
+```
+
+### Run the test:
+
+```bash
+npx testdriverai@latest run add_to_cart_test.yaml
+```
+
+---
+
+## Best practices
+
+1. **Keep Prompts Simple**: Focus on high-level actions or outcomes. Avoid including unnecessary details.
+2. **Use Descriptive Prompts**: Ensure each prompt clearly describes the action or expectation.
+3. **Test the YAML**: Run the converted YAML file to verify that it works as expected.
+4. **Organize Files**: Store YAML files in a structured directory (for example, `testdriver/`) for easy management.
+
+---
+
+By following this guide, you can efficiently convert Gherkin scenarios into TestDriver prompts, enabling seamless integration of existing test cases into your TestDriver workflows.

package/docs/v6/importing/jira.mdx

@@ -0,0 +1,164 @@
+---
+title: "Jira"
+sidebarTitle: "Jira"
+description: "Import user stories from Jira into TestDriver test files."
+icon: "file-image"
+---
+
+# Importing user stories from Jira into TestDriver test files
+
+This guide explains how to extract **user stories** from Jira and convert them into **TestDriver test files**. By automating this process, you can ensure that your user stories are directly translated into actionable test cases for TestDriver.
+
+---
+
+## Workflow overview
+
+1. **Export User Stories from Jira**: Use the Jira API to fetch user stories.
+2. **Convert User Stories to TestDriver YAML**: Transform the user stories into YAML test files.
+3. **Save and Organize Test Files**: Store the generated YAML files in a structured directory.
+4. **Run Tests with TestDriver**: Execute the tests using the TestDriver CLI.
+
+---
+
+## Step 1: Export user stories from Jira
+
+### Prerequisites
+
+1. **Jira API Token**: Generate an API token from your Jira account.
+2. **Jira Base URL**: Your Jira instance URL (for example, `https://yourcompany.atlassian.net`).
+3. **Node.js**: Ensure Node.js is installed on your system.
+
+### Script: Export user stories from Jira
+
+The following script fetches Jira tickets and extracts the **user story title** and **acceptance criteria**.
+
+#### Install dependencies:
+
+```bash
+npm install axios yaml fs
+```
+
+#### Node.js script (`export-jira-user-stories.js`):
+
+```javascript [expandable]
+const axios = require("axios");
+const yaml = require("yaml");
+const fs = require("fs");
+const path = require("path");
+
+// Jira credentials
+const JIRA_BASE_URL = "https://yourcompany.atlassian.net";
+const JIRA_USERNAME = "your-email@example.com";
+const JIRA_API_TOKEN = "your-api-token";
+const JIRA_PROJECT_KEY = "PROJECT_KEY"; // Replace with your Jira project key
+
+// Output directory
+const OUTPUT_DIR = "./testdriver_tests";
+
+// Ensure the output directory exists
+if (!fs.existsSync(OUTPUT_DIR)) {
+  fs.mkdirSync(OUTPUT_DIR, { recursive: true });
+}
+
+// Fetch Jira tickets
+async function fetchJiraTickets() {
+  try {
+    const response = await axios.get(
+      `${JIRA_BASE_URL}/rest/api/2/search?jql=project=${JIRA_PROJECT_KEY}`,
+      {
+        auth: {
+          username: JIRA_USERNAME,
+          password: JIRA_API_TOKEN,
+        },
+        headers: {
+          "Content-Type": "application/json",
+        },
+      },
+    );
+
+    const tickets = response.data.issues.map((issue) => ({
+      id: issue.key,
+      title: issue.fields.summary,
+      acceptanceCriteria:
+        issue.fields.customfield_12345 || "No acceptance criteria provided", // Replace `customfield_12345` with the field ID for "Acceptance Criteria"
+    }));
+
+    // Process each ticket
+    tickets.forEach((ticket) => createYamlFile(ticket));
+    console.log(`Exported ${tickets.length} user stories to ${OUTPUT_DIR}`);
+  } catch (error) {
+    console.error("Error fetching Jira tickets:", error.message);
+  }
+}
+
+// Create a YAML file for each user story
+function createYamlFile(ticket) {
+  const steps = ticket.acceptanceCriteria.split("\n").map((criteria) => ({
+    prompt: criteria.trim(),
+  }));
+
+  const yamlContent = {
+    version: "4.2.18",
+    steps,
+  };
+
+  const fileName = `${ticket.id}.yaml`;
+  const filePath = path.join(OUTPUT_DIR, fileName);
+
+  fs.writeFileSync(filePath, yaml.stringify(yamlContent), "utf8");
+  console.log(`Created file: ${filePath}`);
+}
+
+// Run the script
+fetchJiraTickets();
+```
+
+---
+
+## Step 2: Convert user stories to TestDriver YAML
+
+The script above generates a YAML file for each Jira ticket. Each file contains the **acceptance criteria** as `prompt` entries.
+
+### Example
+
+```yaml testdriver/proj_123.yaml
+version: 6.0.0
+steps:
+  - prompt: The user can log in with valid credentials.
+  - prompt: An error message is displayed for invalid credentials.
+  - prompt: The login page is responsive on mobile devices.
+```
+
+---
+
+## Step 3: Save and organize test files
+
+1. The generated YAML files will be saved in the `testdriver/` directory.
+2. Ensure the directory is part of your TestDriver project structure.
+
+---
+
+## Step 4: Run tests with TestDriver
+
+Use the TestDriver CLI to execute the generated test files.
+
+### Run a single test file:
+
+```bash
+npx testdriverai@latest run testdriver/proj_123.yaml
+```
+
+---
+
+## Best practices
+
+1. **Field Mapping**: Ensure the correct Jira field ID (for example, `customfield_12345`) is used for "Acceptance Criteria."
+2. **Secure Credentials**: Store Jira API credentials in environment variables or secrets.
+3. **Review Generated Files**: Manually review the YAML files to ensure they align with your testing requirements.
+4. **Organize Tests**: Use a structured directory (for example, `testdriver/`) to manage your test files.
+
+---
+
+## Summary
+
+By following this guide, you can automate the process of importing user stories from Jira into TestDriver test files. This ensures that your acceptance criteria are directly translated into actionable tests, streamlining your testing workflows and improving coverage.

package/docs/v6/importing/testrail.mdx

@@ -0,0 +1,162 @@
+---
+title: "TestRail"
+sidebarTitle: "TestRail"
+description: "Import test cases from TestRail into TestDriver."
+icon: "square-pen"
+---
+
+This guide explains how to extract **test cases** from TestRail and convert them into **TestDriver YAML test files**. By automating this process, you can ensure that your TestRail test cases are directly translated into actionable tests for TestDriver.
+
+---
+
+## Workflow overview
+
+1. **Export Test Cases from TestRail**: Use the TestRail API to fetch test cases.
+2. **Convert Test Cases to TestDriver YAML**: Transform the test cases into YAML test files.
+3. **Save and Organize Test Files**: Store the generated YAML files in a structured directory.
+4. **Run Tests with TestDriver**: Execute the tests using the TestDriver CLI.
+
+---
+
+## Step 1: Export test cases from TestRail
+
+### Prerequisites
+
+1. **TestRail API Key**: Obtain your API key from TestRail.
+2. **TestRail Base URL**: Your TestRail instance URL (for example, `https://yourcompany.testrail.io`).
+3. **Node.js**: Ensure Node.js is installed on your system.
+
+### Script: Export test cases from TestRail
+
+The following script fetches TestRail test cases and extracts the **title** and **steps**.
+
+#### Install dependencies:
+
+```bash
+npm install axios yaml fs
+```
+
+#### Node.js script (`export-testrail-test-cases.js`):
+
+```javascript [expandable]
+const axios = require("axios");
+const yaml = require("yaml");
+const fs = require("fs");
+const path = require("path");
+
+// TestRail credentials
+const TESTRAIL_BASE_URL = "https://yourcompany.testrail.io";
+const TESTRAIL_USERNAME = "your-email@example.com";
+const TESTRAIL_API_KEY = "your-api-key";
+const TESTRAIL_PROJECT_ID = 1; // Replace with your TestRail project ID
+
+// Output directory
+const OUTPUT_DIR = "./testdriver_tests";
+
+// Ensure the output directory exists
+if (!fs.existsSync(OUTPUT_DIR)) {
+  fs.mkdirSync(OUTPUT_DIR, { recursive: true });
+}
+
+// Fetch TestRail test cases
+async function fetchTestRailTestCases() {
+  try {
+    const response = await axios.get(
+      `${TESTRAIL_BASE_URL}/index.php?/api/v2/get_cases/${TESTRAIL_PROJECT_ID}`,
+      {
+        auth: {
+          username: TESTRAIL_USERNAME,
+          password: TESTRAIL_API_KEY,
+        },
+        headers: {
+          "Content-Type": "application/json",
+        },
+      },
+    );
+
+    const testCases = response.data.map((testCase) => ({
+      id: testCase.id,
+      title: testCase.title,
+      steps: testCase.custom_steps || "No steps provided", // Replace `custom_steps` with the field ID for test steps if applicable
+    }));
+
+    // Process each test case
+    testCases.forEach((testCase) => createYamlFile(testCase));
+    console.log(`Exported ${testCases.length} test cases to ${OUTPUT_DIR}`);
+  } catch (error) {
+    console.error("Error fetching TestRail test cases:", error.message);
+  }
+}
+
+// Create a YAML file for each test case
+function createYamlFile(testCase) {
+  const steps = testCase.steps.split("\n").map((step) => ({
+    prompt: step.trim(),
+  }));
+
+  const yamlContent = {
+    version: "4.2.18",
+    steps,
+  };
+
+  const fileName = `test_${testCase.id}.yaml`;
+  const filePath = path.join(OUTPUT_DIR, fileName);
+
+  fs.writeFileSync(filePath, yaml.stringify(yamlContent), "utf8");
+  console.log(`Created file: ${filePath}`);
+}
+
+// Run the script
+fetchTestRailTestCases();
+```
+
+---
+
+## Step 2: Convert test cases to TestDriver YAML
+
+The script above generates a YAML file for each TestRail test case. Each file contains the **steps** as `prompt` entries.
+
+### Example
+
+```yaml testdriver/test_123.yaml
+version: 6.0.0
+steps:
+  - prompt: Navigate to the login page.
+  - prompt: Enter valid credentials.
+  - prompt: Click the "Log In" button.
+  - prompt: Verify the dashboard is displayed.
+```
+
+---
+
+## Step 3: Save and organize test files
+
+1. The generated YAML files will be saved in the `testdriver/` directory.
+2. Ensure the directory is part of your TestDriver project structure.
+
+---
+
+## Step 4: Run tests with TestDriver
+
+Use the TestDriver CLI to execute the generated test files.
+
+### Run a Single test file:
+
+```bash
+npx testdriverai@latest run testdriver/test_123.yaml
+```
+
+---
+
+## Best practices
+
+1. **Field Mapping**: Ensure the correct TestRail field ID (for example, `custom_steps`) is used for test steps.
+2. **Secure Credentials**: Store TestRail API credentials in environment variables or secrets.
+3. **Review Generated Files**: Manually review the YAML files to ensure they align with your testing requirements.
+4. **Organize Tests**: Use a structured directory (for example, `testdriver/`) to manage your test files.
+
+---
+
+## Summary
+
+By following this guide, you can automate the process of importing test cases from TestRail into TestDriver test files. This ensures that your test steps are directly translated into actionable tests, streamlining your testing workflows and improving coverage.

package/docs/v6/integrations/electron.mdx

@@ -0,0 +1,146 @@
+---
+title: "Electron"
+sidebarTitle: "Electron"
+description: "Integrate TestDriver with Electron applications"
+icon: "atom"
+---
+
+To integrate **TestDriver** with a workflow that uses the **runner artifact URL** and **GitHub token** for downloading artifacts, you can modify the workflow to include these steps. Below is an example of how to adapt the workflow to ensure TestDriver can access the artifacts.
+
+---
+
+## Updated workflow with TestDriver integration
+
+This workflow builds the application, uploads the build as an artifact, and then uses TestDriver to download the artifact via the runner artifact URL and run tests.
+
+### Workflow file
+
+```yaml .github/workflows/testdriver-integration.yaml
+name: Build and Test with TestDriver
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build Application
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build Application
+        run: npm run build # Ensure your project has a build script
+
+      - name: Upload Build Artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: app-build
+          path: dist/ # Replace with the path to your built application
+
+  test:
+    name: Test Application with TestDriver
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Get Artifact URL
+        id: artifact-url
+        run: |
+          echo "ARTIFACT_URL=${{ github.server_url }}/repos/${{ github.repository }}/actions/artifacts" >> $GITHUB_ENV
+
+      - name: Run TestDriver CLI
+        run: |
+          npx testdriverai@latest run testdriver/test.yaml
+        env:
+          TD_API_KEY: ${{ secrets.TD_API_KEY }}
+          ARTIFACT_URL: ${{ env.ARTIFACT_URL }}
+          FORCE_COLOR: "3"
+```
+
+---
+
+## Using lifecycle files for Electron apps
+
+To ensure your Electron app is downloaded and run in the correct environment, use TestDriver's lifecycle files:
+
+- **lifecycle/provision.yaml**: Download and extract the Electron app artifact here.
+- **lifecycle/prerun.yaml**: Start your Electron app here before the test begins.
+
+### Example:
+
+```yaml testdriver/lifecycle/provision.yaml
+version: 6.0.0
+steps:
+  - prompt: Download Electron app artifact
+    commands:
+      - command: exec
+        lang: pwsh
+        code: |
+          Write-Host "Downloading artifact..."
+          curl -H "Authorization: Bearer ${GITHUB_TOKEN}" \
+          -L "${ARTIFACT_URL}" \
+          --output artifact.zip
+        echo "Extracting artifact..."
+        unzip artifact.zip -d ./app
+```
+
+---
+
+```yaml testdriver/lifecycle/prerun.yaml
+version: 6.0.0
+steps:
+  - prompt: Start Electron app
+    commands:
+      - command: exec
+        lang: pwsh
+        code: |
+          Start-Process -FilePath "./app/your-app-binary" # Replace with the actual binary or executable path
+```
+
+---
+
+## Key changes and explanation
+
+### 1. **Artifact URL Retrieval**
+
+The `Get Artifact URL` step constructs the artifact URL dynamically using the GitHub repository and server URL. This value is passed to the lifecycle files as an environment variable.
+
+### 2. **Downloading and running the app in lifecycle files**
+
+- Download and extract the Electron app in `lifecycle/provision.yaml`.
+- Start the Electron app in `lifecycle/prerun.yaml`.
+- The TestDriver CLI will then execute your tests against the running app.
+
+---
+
+## Secrets configuration
+
+Add the following secrets to your GitHub repository:
+
+1. **`TD_API_KEY`**: Your TestDriver API key.
+2. **`GITHUB_TOKEN`**: Automatically provided by GitHub Actions for authentication.
+
+---
+
+## Benefits of this workflow
+
+1. **Dynamic Artifact Access**: Ensures TestDriver can download artifacts directly from the runner.
+2. **Automated Testing**: Integrates TestDriver to validate the application after the build.
+3. **Secure Authentication**: Uses the GitHub token for secure artifact access.
+4. **Cross-Platform Support**: Can be adapted for different operating systems and environments.
+
+---
+
+By integrating TestDriver with the runner artifact URL and GitHub token, and using lifecycle files, this workflow ensures seamless and secure testing of your Electron application builds.