testdriverai 5.2.2 → 5.3.0

package/docs/importing/gherkin.mdx

@@ -0,0 +1,142 @@
+---
+title: "Gherkin"
+sidebarTitle: "Gherkin"
+---
+
+This guide explains how to convert **Gherkin scenarios** into **TestDriver.ai 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.ai.
+
+---
+
+## What is 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.ai Prompts?
+
+TestDriver.ai prompts are high-level instructions that describe what the AI should do. They are 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.ai Prompts
+
+### Step 1: Understand the Mapping
+
+| **Gherkin Keyword** | **TestDriver.ai 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.ai 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 (e.g., `login_test.yml`).
+2. Ensure the file is stored in the appropriate directory for your TestDriver.ai project (e.g., `testdriver/`).
+
+---
+
+### Step 5: Run the Test with TestDriver.ai
+
+Use the TestDriver.ai CLI to execute the test.
+
+#### Command:
+
+```bash
+testdriverai run login_test.yml
+```
+
+---
+
+## 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
+testdriverai run add_to_cart_test.yml
+```
+
+---
+
+## 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 (e.g., `testdriver/`) for easy management.
+
+---
+
+By following this guide, you can efficiently convert Gherkin scenarios into TestDriver.ai prompts, enabling seamless integration of existing test cases into your TestDriver.ai workflows.

package/docs/importing/jira.mdx

@@ -0,0 +1,172 @@
+---
+title: "Jira"
+sidebarTitle: "Jira"
+---
+
+# Importing User Stories from Jira into TestDriver.ai Test Files
+
+This guide explains how to extract **user stories** from Jira and convert them into **TestDriver.ai test files**. By automating this process, you can ensure that your user stories are directly translated into actionable test cases for TestDriver.ai.
+
+---
+
+## Workflow Overview
+
+1. **Export User Stories from Jira**: Use the Jira API to fetch user stories.
+2. **Convert User Stories to TestDriver.ai 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.ai**: Execute the tests using the TestDriver.ai 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 (e.g., `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
+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}.yml`;
+  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.ai YAML
+
+The script above generates a YAML file for each Jira ticket. Each file contains the **acceptance criteria** as `prompt` entries.
+
+### Example YAML File (`testdriver_tests/PROJ-123.yml`):
+
+```yaml
+version: 4.2.18
+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_tests/` directory.
+2. Ensure the directory is part of your TestDriver.ai project structure.
+
+---
+
+## Step 4: Run Tests with TestDriver.ai
+
+Use the TestDriver.ai CLI to execute the generated test files.
+
+### Run a Single Test File:
+
+```bash
+testdriverai run testdriver_tests/PROJ-123.yml
+
+
+```
+
+### Run All Test Files:
+
+```bash
+testdriverai run testdriver_tests/*.yml
+```
+
+---
+
+## Best Practices
+
+1. **Field Mapping**: Ensure the correct Jira field ID (e.g., `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 (e.g., `testdriver_tests/`) to manage your test files.
+
+---
+
+## Summary
+
+By following this guide, you can automate the process of importing user stories from Jira into TestDriver.ai test files. This ensures that your acceptance criteria are directly translated into actionable tests, streamlining your testing workflows and improving coverage.

package/docs/importing/testrail.mdx

@@ -0,0 +1,161 @@
+---
+title: "TestRail"
+sidebarTitle: "TestRail"
+---
+
+This guide explains how to extract **test cases** from TestRail and convert them into **TestDriver.ai YAML test files**. By automating this process, you can ensure that your TestRail test cases are directly translated into actionable tests for TestDriver.ai.
+
+---
+
+## Workflow Overview
+
+1. **Export Test Cases from TestRail**: Use the TestRail API to fetch test cases.
+2. **Convert Test Cases to TestDriver.ai 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.ai**: Execute the tests using the TestDriver.ai 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 (e.g., `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
+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}.yml`;
+  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.ai YAML
+
+The script above generates a YAML file for each TestRail test case. Each file contains the **steps** as `prompt` entries.
+
+### Example YAML File (`testdriver_tests/test_123.yml`):
+
+```yaml
+version: 4.2.18
+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_tests/` directory.
+2. Ensure the directory is part of your TestDriver.ai project structure.
+
+---
+
+## Step 4: Run Tests with TestDriver.ai
+
+Use the TestDriver.ai CLI to execute the generated test files.
+
+### Run a Single Test File:
+
+```bash
+testdriverai run testdriver_tests/test_123.yml
+```
+
+---
+
+## Best Practices
+
+1. **Field Mapping**: Ensure the correct TestRail field ID (e.g., `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 (e.g., `testdriver_tests/`) to manage your test files.
+
+---
+
+## Summary
+
+By following this guide, you can automate the process of importing test cases from TestRail into TestDriver.ai test files. This ensures that your test steps are directly translated into actionable tests, streamlining your testing workflows and improving coverage.

package/docs/integrations/electron.mdx

@@ -0,0 +1,152 @@
+---
+title: "Electron"
+---
+
+To integrate **TestDriver.ai** 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.ai can access the artifacts.
+
+---
+
+## Updated Workflow with TestDriver.ai Integration
+
+This workflow builds the application, uploads the build as an artifact, and then uses TestDriver.ai to download the artifact via the runner artifact URL and run tests.
+
+### Workflow File: `.github/workflows/testdriver-integration.yml````yaml
+name: Build and Test with TestDriver.ai
+
+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@v3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '16'
+
+      - 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.ai
+    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 Tests with TestDriver.ai
+        uses: testdriverai/action@main
+        with:
+          key: ${{ secrets.TESTDRIVER_API_KEY }}
+          prompt: |
+            1. Download the artifact from the runner URL
+            2. Extract the artifact
+            3. Run the application
+            4. Verify the main window loads correctly
+            5. Perform additional tests
+          prerun: |
+            echo "Downloading artifact..."
+            curl -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
+              -L "${{ env.ARTIFACT_URL }}" \
+              --output artifact.zip
+            echo "Extracting artifact..."
+            unzip artifact.zip -d ./app
+            echo "Running application..."
+            ./app/your-app-binary # Replace with the actual binary or executable path
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          FORCE_COLOR: "3"
+
+```
+
+---
+
+## 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 ensures the TestDriver.ai runner can download the artifact.```yaml
+- name: Get Artifact URL
+  id: artifact-url
+  run: |
+    echo "ARTIFACT_URL=${{ github.server_url }}/repos/${{ github.repository }}/actions/artifacts" >> $GITHUB_ENV
+
+```
+
+---
+
+### 2. **Downloading the Artifact**
+The `prerun` script in the TestDriver.ai action uses `curl` to download the artifact from the runner URL. The `GITHUB_TOKEN` is passed as a header for authentication.```yaml
+prerun: |
+  echo "Downloading artifact..."
+  curl -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
+    -L "${{ env.ARTIFACT_URL }}" \
+    --output artifact.zip
+  echo "Extracting artifact..."
+  unzip artifact.zip -d ./app
+  echo "Running application..."
+  ./app/your-app-binary # Replace with the actual binary or executable path
+
+```
+
+---
+
+### 3. **TestDriver.ai Integration**
+The TestDriver.ai action is configured to:
+- Download the artifact.
+- Extract the artifact.
+- Run the application.
+- Execute the specified test steps.```yaml
+- name: Run Tests with TestDriver.ai
+  uses: testdriverai/action@main
+  with:
+    key: ${{ secrets.TESTDRIVER_API_KEY }}
+    prompt: |
+      1. Download the artifact from the runner URL
+      2. Extract the artifact
+      3. Run the application
+      4. Verify the main window loads correctly
+      5. Perform additional tests
+
+```
+
+---
+
+## Secrets Configuration
+
+Add the following secrets to your GitHub repository:
+1. **`TESTDRIVER_API_KEY`**: Your TestDriver.ai API key.
+2. **`GITHUB_TOKEN`**: Automatically provided by GitHub Actions for authentication.
+
+---
+
+## Benefits of This Workflow
+
+1. **Dynamic Artifact Access**: Ensures TestDriver.ai can download artifacts directly from the runner.
+2. **Automated Testing**: Integrates TestDriver.ai 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.ai with the runner artifact URL and GitHub token, this workflow ensures seamless testing of your application builds.