practitest-results-uploader

A CLI tool to upload automated test results to PractiTest, supporting creation of test sets, test runs, and custom fields from XML reports. Unlike the official PractiTest Firecracker tool, this CLI uses the test ID (extracted via regex from the test name in your XML) to match and upload results, instead of relying on the test name. This approach ensures more robust and accurate mapping between your automated results and PractiTest entities.

Installation

Prerequisites:

• Node.js 14.x or later must be installed.

Optionally, you can add practitest-results-uploader as a devDependency to your project for version control and reproducibility:

npm install --save-dev practitest-results-uploader

Then run it with npx as shown below.

npx practitest-results-uploader --api-token <TOKEN> --project-id <ID> --reports-path <path/to/results.xml> --testset-name "<Test Set Name>" --id-pattern "(\\d+)" [other options]

Features

• Uses test IDs instead of test names for mapping:
• Uploads test results from XML (JUnit-style) to PractiTest.
• Automatically creates or finds test sets by name.
• Adds missing tests to the set as needed.
• Supports custom fields for both test sets and test runs.
• Batches uploads for performance and reliability.
• Designed for use in automation pipelines (Jenkins, GitHub Actions, etc.).

Usage

Run the tool using npx (no global installation required):

npx practitest-results-uploader --api-token <TOKEN> --project-id <ID> --reports-path <path/to/results.xml> --testset-name "<Test Set Name>" --id-pattern "(\\d+)" [other options]

New: Update Custom Fields in Original PractiTest Tests

You can now update custom fields for all original PractiTest tests referenced in your XML using the --update-tests-fields option. This is useful for marking tests as Automated, setting technology, or any other custom field.

Example:

npx practitest-results-uploader \
  --api-token <TOKEN> \
  --project-id <ID> \
  --reports-path results.xml \
  --testset-name "My Test Set" \
  --id-pattern "(\\d+)" \
  --update-tests-fields '{"---f-123456":"Automated","---f-789012":"Playwright"}'

This will update the custom fields ---f-123456 and ---f-789012 for each test in PractiTest referenced by display-id in your XML, but only if the value is different from the current one.

Arguments

| Argument | Type | Required | Description | |-------------------------------|----------|----------|---------------------------------------------------------------------------------------------| | --api-token | string | Yes | PractiTest API token. | | --project-id | number | Yes | PractiTest Project ID. | | --reports-path | string | Yes | Path to the XML results file (JUnit format). | | --testset-name | string | Yes | Name of the test set in PractiTest. If it does not exist, it will be created. | | --id-pattern | string | Yes | Regex to extract the PractiTest display ID from the test name (e.g., "(\\d+)"). | | --batch-size | number | No | Number of results to upload per request (default: 20). | | --additional-testset-fields | string | No | JSON string for custom fields of the test set. | | --additional-run-fields | string | No | JSON string for custom fields of each test run. | | --update-tests-fields | string | No | JSON string with custom fields to update in the original PractiTest tests (by display-id). | | --help | flag | No | Show help. |

Example: Minimal usage

npx practitest-results-uploader \
  --api-token 123456 \
  --project-id 7890 \
  --reports-path results.xml \
  --testset-name "My Test Set" \
  --id-pattern "(\\d+)"

Example: With custom fields and batch size

npx practitest-results-uploader \
  --api-token 123456 \
  --project-id 7890 \
  --reports-path results.xml \
  --testset-name "My Test Set" \
  --id-pattern "(\\d+)" \
  --batch-size 10 \
  --additional-testset-fields '{"custom-fields": {"field1": "value1"}}' \
  --additional-run-fields '{"custom-fields": {"env": "staging"}}'

How it works

• Feed with XML report containing test results.
• For each test case, extracts the PractiTest display ID in one of two ways:
  1. First, checks for an id attribute directly in the XML testcase element
  2. If no id attribute is found, uses the provided regex pattern to extract the ID from the test name
• Finds or creates the test set in PractiTest.
• Ensures all referenced tests are present in the Test Set (adds them if missing).
• Uploads test run results in batches.
• Supports custom fields for both test sets and runs.

CI/CD Integration Example

Jenkins, GitHub Actions, or any shell-based pipeline:

npx practitest-results-uploader --api-token $PRACTITEST_TOKEN --project-id 7890 --reports-path results.xml --testset-name "My Test Set" --id-pattern "(\\d+)"

Notes

• The tool expects the XML file to be in JUnit format, with test names containing the PractiTest display ID (e.g., [1234] - should do something).
• If a test case does not contain a valid display ID, it will be skipped with a warning.
• If a test is not found in PractiTest, it will be skipped with a warning.
• If a test is not present in the set, it will be added automatically.
• If a test is marked as SKIPPED in the XML, it will be reported as NO RUN in PractiTest.
• Custom fields must be provided as valid JSON strings.

Troubleshooting

• API errors: Check your API token and project ID.
• Regex issues: Make sure your --id-pattern matches the display ID in your test names.
• XML parsing errors: Ensure your report is valid JUnit XML.
• Batch upload errors: The tool will retry failed uploads individually and log errors.

License

MIT