Skip to main content
This guide demonstrates how to convert user stories from CSV files into individual TestDriver test files using Node.js. Each user story will be saved as its own YAML test file, and the tests will be executed in parallel using a GitHub Actions workflow.

​
Workflow overview

  1. Export User Stories: Extract user stories from TestRail, CSV, or Jira.
  2. Convert to Test Files: Use a Node.js script to generate individual YAML test files for each user story.
  3. Run Tests: Use a CI/CD workflow to execute the tests in parallel with the TestDriver CLI.

​
Step 1: Export user stories

Export user stories from your source (TestRail, CSV, or Jira) and save them in a structured format (for example, JSON or CSV). For example:

​
Example CSV file (user_stories.csv):

User Story IDUser Story TitleDescription
1Log in to the applicationUser logs in with valid credentials.
2Search for a productUser searches for a product by name.
3Add product to cartUser adds a product to the cart.

​
Step 2: Node.js script to convert user stories into test files

Create a Node.js script to read the exported data and generate individual YAML test files for each user story.

​
Install required dependencies

npm install yaml fs csv-parser

​
Node.js script (generate-tests.js)

const fs = require("fs");
const path = require("path");
const yaml = require("yaml");
const csv = require("csv-parser");

// Input and output directories
const inputFile = "./user_stories.csv";
const outputDir = "./testdriver";

// Ensure the output directory exists
if (!fs.existsSync(outputDir)) {
  fs.mkdirSync(outputDir, { recursive: true });
}

// Function to generate a YAML test file for each user story
function generateTestFile(userStory) {
  const {
    "User Story ID": id,
    "User Story Title": title,
    Description,
  } = userStory;

  const testContent = {
    version: "6.0.0",
    steps: [
      {
        prompt: title,
      },
    ],
  };

  const yamlContent = yaml.stringify(testContent);
  const fileName = `test_${id}.yaml`;
  const filePath = path.join(outputDir, fileName);

  fs.writeFileSync(filePath, yamlContent, "utf8");
  console.log(`Generated test file: ${filePath}`);
}

// Read the CSV file and generate test files
fs.createReadStream(inputFile)
  .pipe(csv())
  .on("data", (row) => {
    generateTestFile(row);
  })
  .on("end", () => {
    console.log("All test files generated successfully!");
  });

​
Run the script

node generate-tests.js
This script will generate individual YAML test files (for example, test_1.yaml, test_2.yaml) in the testdriver/ directory.

​
Step 3: CI/CD workflow to run tests in parallel

Create a CI/CD workflow to execute the generated test files in parallel using the TestDriver CLI. Below is a generalized example for any CI/CD system (adapt for your platform):
.github/workflows/testdriver.yaml
name: Run TestDriver Tests

on:
  push:
    branches:
      - main
  pull_request:
  workflow_dispatch:

jobs:
  gather-test-files:
    name: Gather Test Files
    runs-on: ubuntu-latest
    outputs:
      test_files: ${{ steps.test_list.outputs.files }}
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Find all test files
        id: test_list
        run: |
          FILES=$(ls ./testdriver/*.yaml)
          FILES_JSON=$(echo "$FILES" | jq -R -s -c 'split("\n")[:-1]')
          echo "files=$FILES_JSON" >> $GITHUB_OUTPUT

  run-tests:
    name: Run Tests in Parallel
    needs: gather-test-files
    runs-on: ubuntu-latest
    strategy:
      matrix:
        test_file: ${{ fromJson(needs.gather-test-files.outputs.test_files) }}
      fail-fast: false
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Run TestDriver CLI
        run: npx testdriverai@latest run ${{ matrix.test_file }}
        env:
          TD_API_KEY: ${{ secrets.TD_API_KEY }}

​
Step 4: Secure API key

Store your TestDriver API key as a GitHub secret (for example, TD_API_KEY) to securely authenticate your tests.

​
Step 5: Commit and push

  1. Commit the generate-tests.js script, user_stories.csv, and .github/workflows/run-tests.yaml to your repository.
  2. Push the changes to the main branch.

​
Step 6: Run the workflow

The GitHub Actions workflow will automatically:
  1. Gather all test files in the testdriver/ directory.
  2. Execute each test file in parallel using the matrix strategy.

​
Example output

  • Generated Test Files:
    • testdriver/test_1.yaml
    • testdriver/test_2.yaml
    • testdriver/test_3.yaml
  • GitHub Actions Dashboard:
    • Each test file is executed as a separate job, and the results are displayed in the Actions tab.

​
Conclusion

This setup automates the process of converting user stories into individual test files and running them in parallel using the TestDriver CLI in your CI/CD pipeline. It ensures comprehensive test coverage while optimizing execution time.