Skip to main content

QA Sphere CLI Tool: Usage

Installation​

Prerequisites​

  • Node.js version 18.0.0 or higher

Installation Methods​

  1. Via NPM (Recommended)

    npm install -g qas-cli

  2. Via Source Code

    git clone https://github.com/Hypersequent/qas-cli.git
    cd qas-cli
    npm install
    npm run build
    npm link

    Verify the installation:

    qasphere --version

Configuration​

The QAS CLI requires two environment variables to function properly:

  • QAS_TOKEN - QASphere API token
  • QAS_URL - Base URL of your QA Sphere instance

You can create your API key under the QA Sphere settings.

To do that:

  1. Go to Settings by clicking the gear icon Settings wheel in the top right corner.
  2. Click API Keys
  3. Click Create API Key and generate one

Api Key Screenshot You can set these variables in two ways:

  1. Environment Variables: Export them in your shell:

    export QAS_TOKEN=your_token_here
    export QAS_URL=your_qas_url

  2. Configuration File: Create a .qaspherecli file in your project directory or any parent directory:

    # .qaspherecli
    QAS_TOKEN=your_token
    QAS_URL=your_qas_url

    # Example with real values:
    # QAS_TOKEN=tst0000001.1CKCEtest_JYyckc3zYtest.dhhjYY3BYEoQH41e62itest
    # QAS_URL=https://qas.eu1.qasphere.com

Using the junit-upload Command​

The junit-upload command is used to upload JUnit XML test results to QA Sphere. The command will automatically create a new test run if no run URL is provided, or upload to an existing run if a run URL is specified.

Basic Syntax​

# Create new test run automatically
qasphere junit-upload <path-to-junit-xml>

# Upload to existing test run
qasphere junit-upload -r <run-url> <path-to-junit-xml>

Options​

  • -r, --run-url: Optional URL of the QA Sphere test run. If not provided, a new test run will be created automatically
  • --attachments: Upload detected attachments with test results
  • --force: Ignore errors and continue uploading

Examples​

  1. Create a new test run automatically and upload results:

    qasphere junit-upload ./path/to/junit.xml

  2. Upload to an existing test run:

    qasphere junit-upload -r https://qas.eu1.qasphere.com/project/P1/run/23 ./path/to/junit.xml

  3. Create a new test run and upload multiple XML files:

    qasphere junit-upload ./*.xml

  4. Upload multiple XML files to an existing test run:

    qasphere junit-upload --run-url https://qas.eu1.qasphere.com/project/P1/run/23 ./*.xml

  5. Create a new test run and upload with attachments:

    qasphere junit-upload --attachments ./junit.xml

  6. Upload with attachments to an existing test run:

    qasphere junit-upload -r https://qas.eu1.qasphere.com/project/P1/run/23 --attachments ./junit.xml

JUnit XML Requirements​

To ensure successful uploads, your JUnit XML files should follow these naming conventions:

  1. Test case names should contain QA Sphere test case references in the format PROJECT-SEQUENCE.
  2. PROJECT is your QASphere project code.
  3. SEQUENCE is at least a three-digit test case sequence number from the QASphere test case URL.

Examples of valid test case names:

  • PRJ-312: Login with valid credentials
  • Login with valid credentials: PRJ-312

Troubleshooting​

  1. If you encounter permission errors, try:

    chmod +x ./build/bin/qasphere.js

  2. For help with any command, use the -h flag:

    qasphere junit-upload -h

  3. Ensure your JUnit XML contains matching test cases to avoid upload errors.

By following these guidelines, you can effectively use the QAS CLI tool to integrate your automated test results with QA Sphere, streamlining your test management process.