PractiTest Aegis Manager CLI

Description

PractiTest Aegis Manager is a CLI (Command Line Interface) tool designed to interact with the PractiTest API. It allows you to fetch and store snapshots of test data, requirements, test sets, test runs, instances, fields, custom fields, and issues from your PractiTest library in a single operation. The tool includes a robust retry mechanism to handle temporary API failures, making it reliable even for large projects with many data points. This tool can be run manually or scheduled to run daily, ensuring you always have the latest data available for analysis and reporting.

Features

• Command line interface for easy use and integration
• Fetches all tests, requirements, test sets, test runs, instances, fields, custom fields, and issues from the PractiTest API in a single command
• Built-in retry mechanism for improved reliability when dealing with API timeouts or server errors
• Saves snapshots of all PractiTest data in JSON format in a timestamp-based directory
• Easily integrates with any CI/CD system (Jenkins, GitHub Actions, etc.)
• Configurable via parameters or environment variables
• Comprehensive error handling and progress reporting

Project Structure

practitest-aegis-manager
├── src
│   ├── index.ts               # Application entry point and CLI
│   ├── practitest-api.ts      # Functions to interact with PractiTest API
│   ├── snapshot-service.ts    # Processes and saves test data snapshot
│   └── types
│       └── index.ts           # TypeScript interfaces and types
├── package.json               # npm configuration and dependencies
├── tsconfig.json              # TypeScript configuration
└── README.md                  # Project documentation

Installation

Global (recommended for general use)

npm install -g practitest-aegis-manager

Local with npx (no installation)

npx practitest-aegis-manager [options]

CLI Usage

Available Options

practitest-aegis-manager [options]

Options:
  -t, --api-token         PractiTest API Token                      [string]
  -p, --project-id        PractiTest Project ID                     [string]
  -o, --output            Path to save the snapshots                [string] [default: "./"]
  -i, --include-relationships Include linked entities in requirements [boolean] [default: false]
  -h, --help              Show help                                 [boolean]
  -v, --version           Show version number                       [boolean]

Usage Examples

1. With command line parameters

   practitest-aegis-manager --api-token "your-api-token" --project-id "123" --output "./snapshots"

2. With environment variables

   export PRACTITEST_API_TOKEN="your-api-token"
   export PRACTITEST_PROJECT_ID="123"
   practitest-aegis-manager --output "./snapshots"

3. Using npx (without global installation)

   npx practitest-aegis-manager --api-token "your-api-token" --project-id "123"

Integration with CI/CD systems

Jenkins (example)

To set up a Jenkins job that runs this CLI:

Configure Credentials in Jenkins

1. Create Credentials in Jenkins:

   • Go to Jenkins > Manage Jenkins > Credentials > System > Global credentials
   • Click "Add credentials"
   • Select "Username with password" or "Secret text" (for each credential)
   • For ID, enter practitest-api-token and practitest-project-id
   • Store the API token and Project ID respectively
   • Click "OK"

2. Create a Jenkins Job:

   • Create a new Pipeline or Freestyle job
   • Configure the following script section:

```groovy
// Jenkins Pipeline example
pipeline {
    agent {
        docker {
            image 'node:16'
        }
    }
    
    triggers {
        cron('H 0 * * *') // Daily at midnight
    }
    
    environment {
        PRACTITEST_API_TOKEN = credentials('practitest-api-token')
        PRACTITEST_PROJECT_ID = credentials('practitest-project-id')
    }
    
    stages {
        stage('Snapshot') {
            steps {
                sh 'mkdir -p snapshots'
                sh 'npx practitest-aegis-manager --api-token $PRACTITEST_API_TOKEN --project-id $PRACTITEST_PROJECT_ID --output ./snapshots/tests'
                sh 'npx practitest-aegis-manager --api-token $PRACTITEST_API_TOKEN --project-id $PRACTITEST_PROJECT_ID --requirements --output ./snapshots/requirements'
                archiveArtifacts artifacts: 'snapshots/*.json'
            }
        }
    }
}

GitHub Actions (example)

name: PractiTest Snapshot

on:
  schedule:
    - cron: '0 0 * * *'  # Run every day at midnight
  workflow_dispatch:  # Allow manual execution

jobs:
  snapshot:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '16'
      - run: npm ci
      - run: |
          mkdir -p snapshots
          npx practitest-aegis-manager --api-token ${{ secrets.PRACTITEST_API_TOKEN }} --project-id ${{ secrets.PRACTITEST_PROJECT_ID }} --output ./snapshots
      - uses: actions/upload-artifact@v2
        with:
          name: practitest-snapshots
          path: snapshots/

GitLab CI (example)

practitest-snapshot:
  image: node:16
  script:
    - npm ci
    - mkdir -p snapshots
    - npx practitest-aegis-manager --api-token $PRACTITEST_API_TOKEN --project-id $PRACTITEST_PROJECT_ID --output ./snapshots
  artifacts:
    paths:
      - snapshots/
  only:
    - schedules

Usage

# Basic usage to fetch all entity types
practitest-aegis-manager --api-token YOUR_TOKEN --project-id 12345

# Save snapshots to a specific directory
practitest-aegis-manager --api-token YOUR_TOKEN --project-id 12345 --output ./snapshots

# Include relationships for requirements, test sets, and issues
practitest-aegis-manager --api-token YOUR_TOKEN --project-id 12345 --include-relationships

Each snapshot is stored in a timestamp-based directory with separate files for tests, requirements, test sets, and test runs:

./snapshots/snapshot-2025-09-25_12-30-45/
  ├── tests.json
  ├── requirements.json
  ├── test-sets.json
  ├── test-runs.json
  ├── instances.json
  ├── fields.json
  ├── custom-fields.json
  └── issues.json

Note: For large projects, the PractiTest API may have limitations when fetching test runs or instances. The tool is designed to handle this gracefully and continue with the rest of the snapshots even if test runs cannot be fetched.

Once set up, the PractiTest Aegis Manager will automatically fetch the latest data from PractiTest and save it as a snapshot. The tool fetches the following data entities:

1. Tests: All test cases in the project
2. Requirements: Project requirements with optional relationships
3. Test Sets: Test set configurations with optional relationships
4. Test Runs: Execution history for tests in your project
5. Instances: Test instances across test sets
6. Fields: Field definitions used in the project
7. Custom Fields: Custom field definitions specific to your project
8. Issues: Issues/defects tracked in the project with optional relationships

The retry mechanism automatically handles temporary server errors or timeouts, making multiple attempts before giving up. Progress is displayed during the fetch process, especially helpful for large projects with many pages of data.

You can customize the output format and storage location by modifying the snapshot-service.ts file.

Contributing

Contributions are welcome! Please submit a pull request or open an issue for any enhancements or bug fixes.

License

This project is licensed under the MIT License. See the LICENSE file for more details.