lupin-sw-ut-report 1.0.6

Tool used to generate a test reports.

lupin_sw_ut_report

This project is a comprehensive software unit test reporting and management tool that processes test files and integrates with Jama for test lifecycle management. It converts test files (in .txt and .xml formats) into structured Markdown reports and provides advanced Jama integration for automated test case creation and result tracking.

What This Tool Does

The lupin_sw_ut_report tool serves as a bridge between your test execution results and Jama test management system, providing three main capabilities:

1. Test File Processing and Report Generation

• Parses Multiple Test Formats: Processes both .txt files (with Given-When-Then format) and .xml files (JUnit-style test results)
• Generates Structured Reports: Creates comprehensive Markdown reports with test summaries, detailed test cases, and requirement coverage
• Extracts Test Metadata: Automatically extracts test names, status, dates, tags, and requirement IDs from test files
• Supports Given-When-Then Format: Specifically designed to parse and format BDD-style test scenarios with Given/When/Then/And steps

2. Jama Integration for Test Case Management

• Automated Test Case Creation: Creates unit test cases in Jama based on parsed test files
• Module Organization: Organizes tests by module in Jama folder structure
• Requirement Linking: Automatically links test cases to requirements using extracted requirement IDs
• Status Management: Updates test case statuses and workflow states in Jama
• Dry-Run Capability: Preview changes before applying them to Jama

3. Test Result Tracking and Reporting

• Test Result Push: Pushes test execution results to Jama test cycles
• Version-Based Organization: Organizes test results by software version
• Test Plan Integration: Creates and manages test plans and test cycles in Jama
• Comprehensive Logging: Provides detailed logging for debugging and audit trails

4. CI/CD Pipeline Integration

• Automated Test Reporting: Designed to run automatically in CI/CD pipelines (GitLab CI, Jenkins, GitHub Actions, etc.)
• Version Tag Integration: Automatically extracts version information from CI commit tags ($CI_COMMIT_TAG)
• Pipeline Variable Support: Seamlessly integrates with CI/CD environment variables and pipeline metadata
• Exit Code Management: Provides proper exit codes for pipeline success/failure detection
• Headless Operation: Runs without user interaction, perfect for automated environments
• Configurable Logging: Supports both console and file logging for pipeline artifact collection

Key Features

• Multi-Format Support: Handles both TXT (BDD format) and XML (JUnit format) test files
• Jama Cloud Integration: Full integration with Jama Cloud for test management
• Requirement Traceability: Automatic linking of tests to requirements via ID extraction
• Flexible Configuration: Supports both command-line parameters and environment variables
• CI/CD Pipeline Integration: Built-in support for automated execution in CI/CD environments (GitLab CI, Jenkins, GitHub Actions)
• Comprehensive Reporting: Generates both Markdown and HTML reports
• Error Handling: Robust error handling with detailed logging and exit codes
• Dry-Run Mode: Safe testing of Jama operations without making changes

Setting Up a Python Virtual Environment (Recommended for Development)

A Python virtual environment is an isolated workspace that allows you to install dependencies for a project without affecting your global Python installation or other projects. This is especially useful for development, as it helps avoid dependency conflicts and keeps your system clean.

Note: This setup is recommended for developers who want to contribute to or test the project locally. End users installing via pip install lupin-sw-ut-report do not need to follow these steps.

Why Use a Virtual Environment?

• Keeps project dependencies isolated from other Python projects and your system Python.
• Prevents version conflicts between packages.
• Makes it easy to manage and reproduce development environments.

Step-by-Step Setup (Windows)

1. Create a virtual environment in the project root:

   python -m venv .lupin_sw_ut_report
   

2. Activate the virtual environment:

   .\.lupin_sw_ut_report\Scripts\activate
   

   You should see the environment name (e.g., (.lupin_sw_ut_report)) appear in your terminal prompt.

3. Install the project in editable mode:

   pip install -e .
   

   This installs the project in "editable mode," meaning any changes you make to the source code will immediately affect your environment without needing to reinstall. This is ideal for development and testing.

4. Deactivate the virtual environment when done:

   deactivate
   

   This returns your terminal to the global Python environment.

Tip: The .lupin_sw_ut_report folder should be added to your .gitignore file to avoid committing it to version control.

Installation

Run pip install lupin-sw-ut-report

Basic Usage

This project provides a command-line interface to generate reports from a folder containing test files (.txt and .xml).

To run the script, use the following command:

sw-ut-report --input-folder <path/to/your/input-folder>

Configuration

This project supports configuration through both command-line parameters and environment variables. Command-line parameters take priority over environment variables, which in turn take priority over default values.

Priority Order

1. Command-line parameters (highest priority)
2. Environment variables
3. Default values (lowest priority)

Command-Line Parameters

Basic Parameters

Parameter	Type	Required	Description
--input-folder	string	Yes	Path to the folder containing the txt and xml files
--version	flag	No	Show version information and exit

Report Generation Parameters

Parameter	Type	Default	Description
--markdown	flag	True	Generate markdown report (default behavior)
--no-markdown	flag	False	Do not generate markdown report

Jama Integration Parameters

Parameter	Type	Required	Description
--create-ut	flag	No	Create/update unit tests in Jama
--module-name	string	Yes*	Module name for Jama UT creation (required with --create-ut)
--dry-run	flag	False	Show what would be done without making changes to Jama
--push-ut-test-results	string	No	Push UT test results to Jama for the specified version

Jama Configuration Parameters

These parameters can be used to override environment variables for Jama integration:

Parameter	Type	Description
--jama-project-id	string	Overrides JAMA_DEFAULT_PROJECT_ID environment variable
--jama-test-set-id	string	Overrides JAMA_TEST_SET_ID environment variable (default: "SmlPrep-SET-359")
--jama-ut-test-case-id	string	Overrides JAMA_UT_TEST_CASE_ID environment variable (default: "SmlPrep-UT-1")
--jama-id-prefix	string	Prefix to replace in covers fields (default: "SmlPrep")

CI/CD Parameters

Parameter	Type	Description
--ci-commit-tag	string	Pipeline GitLab variable $CI_COMMIT_TAG

Logging Parameters

Parameter	Type	Default	Description
--log-level	string	"INFO"	Logging level (DEBUG, INFO, WARNING, ERROR)
--log-file	string	None	Path to log file (optional)

Complete Usage Examples

Basic Report Generation

Generate Markdown Report Only

# Basic markdown generation
sw-ut-report --input-folder /path/to/test/files

# With custom logging
sw-ut-report --input-folder /path/to/test/files --log-level DEBUG

# Skip markdown generation (useful for Jama-only operations)
sw-ut-report --input-folder /path/to/test/files --no-markdown

Jama Integration Examples

Create Unit Tests in Jama

# Basic UT creation
sw-ut-report --input-folder /path/to/test/files --create-ut --module-name "MyModule"

# Dry run to preview changes
sw-ut-report --input-folder /path/to/test/files --create-ut --module-name "MyModule" --dry-run

# With custom logging for debugging
sw-ut-report --input-folder /path/to/test/files --create-ut --module-name "MyModule" \
  --log-level DEBUG --log-file /path/to/jama-creation.log

Push Test Results to Jama

# Push results for a specific version
sw-ut-report --input-folder /path/to/test/files --push-ut-test-results "v1.2.3"

# With custom Jama configuration
sw-ut-report --input-folder /path/to/test/files --push-ut-test-results "v1.2.3" \
  --jama-project-id "8" --jama-test-set-id "MyProject-SET-123"

Override Jama Configuration

# Override all Jama settings
sw-ut-report --input-folder /path/to/test/files --create-ut --module-name "MyModule" \
  --jama-project-id "8" \
  --jama-test-set-id "MyProject-SET-123" \
  --jama-ut-test-case-id "MyProject-UT-456" \
  --jama-id-prefix "CustomPrefix"

CI/CD Integration Examples

GitLab CI Pipeline

# With CI commit tag
sw-ut-report --input-folder /path/to/test/files --ci-commit-tag "$CI_COMMIT_TAG"

# Complete CI pipeline with Jama integration
sw-ut-report --input-folder /path/to/test/files \
  --create-ut \
  --module-name "$CI_PROJECT_NAME" \
  --ci-commit-tag "$CI_COMMIT_TAG" \
  --log-level INFO \
  --log-file "/tmp/ut-report-$CI_PIPELINE_ID.log"

Advanced Configuration Examples

Multi-Environment Setup

# Development environment
sw-ut-report --input-folder /path/to/test/files --create-ut --module-name "MyModule" \
  --jama-id-prefix "DevProject" \
  --log-level DEBUG

# Production environment
sw-ut-report --input-folder /path/to/test/files --create-ut --module-name "MyModule" \
  --jama-id-prefix "ProdProject" \
  --log-level INFO

Comprehensive Workflow

# Complete workflow: generate report + create UTs + push results
sw-ut-report --input-folder /path/to/test/files \
  --create-ut \
  --module-name "MyModule" \
  --push-ut-test-results "v1.2.3" \
  --ci-commit-tag "v1.2.3" \
  --jama-project-id "8" \
  --jama-test-set-id "MyProject-SET-123" \
  --jama-ut-test-case-id "MyProject-UT-456" \
  --jama-id-prefix "MyProject" \
  --log-level INFO \
  --log-file "/var/log/ut-report.log"

Troubleshooting Examples

Debug Mode

# Maximum debugging information
sw-ut-report --input-folder /path/to/test/files \
  --create-ut \
  --module-name "MyModule" \
  --dry-run \
  --log-level DEBUG \
  --log-file "/tmp/debug.log"

Validation Mode

# Validate configuration without making changes
sw-ut-report --input-folder /path/to/test/files \
  --create-ut \
  --module-name "MyModule" \
  --dry-run \
  --log-level INFO

Environment Variables

This project supports several environment variables for configuration, particularly for Jama integration and sandbox environments.

Jama Connection Variables (Required for Jama Integration)

Variable	Required	Description
JAMA_URL	Yes	Your Jama instance URL
JAMA_CLIENT_ID	Yes	Your Jama client ID for authentication
JAMA_CLIENT_PASSWORD	Yes	Your Jama client password for authentication
JAMA_DEFAULT_PROJECT_ID	Yes	Default project ID for Jama operations

Jama Configuration Variables (Optional)

Variable	Default	Description
JAMA_TEST_SET_ID	"SmlPrep-SET-359"	Test set container for unit test organization
JAMA_UT_TEST_CASE_ID	"SmlPrep-UT-1"	Test case ID used for finding the UT test group
JAMA_ID_PREFIX	"SmlPrep"	Default prefix for ID replacement
JAMA_PREFIXES_TO_REPLACE	"SmlPrep"	Comma-separated list of prefixes to replace

Environment Variable Examples

Basic Jama Configuration

# Required Jama connection settings
export JAMA_URL="https://your-company.jamacloud.com"
export JAMA_CLIENT_ID="your-client-id"
export JAMA_CLIENT_PASSWORD="your-client-password"
export JAMA_DEFAULT_PROJECT_ID="8"

Custom Jama Configuration

# Optional: Custom test set and test case IDs
export JAMA_TEST_SET_ID="YourCustom-SET-123"
export JAMA_UT_TEST_CASE_ID="YourCustom-UT-456"

# Custom ID prefix
export JAMA_ID_PREFIX="MyProject"
export JAMA_PREFIXES_TO_REPLACE="SmlPrep,OldProject"

Development Environment Setup Scripts

PowerShell Script (Windows)

Create a file named setup-dev-env.ps1:

# Development Environment Setup Script for lupin_sw_ut_report
# Usage: .\setup-dev-env.ps1

Write-Host "Setting up development environment variables for lupin_sw_ut_report..." -ForegroundColor Green

# Required Jama connection settings (UPDATE THESE VALUES)
$env:JAMA_URL = "https://your-dev-company.jamacloud.com"
$env:JAMA_CLIENT_ID = "your-dev-client-id"
$env:JAMA_CLIENT_PASSWORD = "your-dev-client-password"
$env:JAMA_DEFAULT_PROJECT_ID = "8"

# Optional: Development-specific configuration
$env:JAMA_TEST_SET_ID = "DevProject-SET-123"
$env:JAMA_UT_TEST_CASE_ID = "DevProject-UT-456"
$env:JAMA_ID_PREFIX = "DevProject"
$env:JAMA_PREFIXES_TO_REPLACE = "SmlPrep,OldProject"

Write-Host "Environment variables set successfully!" -ForegroundColor Green
Write-Host "Jama URL: $env:JAMA_URL" -ForegroundColor Yellow
Write-Host "Project ID: $env:JAMA_DEFAULT_PROJECT_ID" -ForegroundColor Yellow
Write-Host "Test Set ID: $env:JAMA_TEST_SET_ID" -ForegroundColor Yellow

# Test the configuration
Write-Host "`nTesting configuration..." -ForegroundColor Cyan
sw-ut-report --version

Logging Configuration

The application supports configurable logging through command-line parameters and environment variables.

Log Levels

Level	Description
DEBUG	Detailed information for debugging
INFO	General information about program execution
WARNING	Warning messages for potential issues
ERROR	Error messages for serious problems

Logging CLI Parameters

Parameter	Type	Default	Description
--log-level	string	"INFO"	Set the logging level for console output
--log-file	string	None	Optional path to log file (enables file logging)

Logging Examples

# Debug logging to console only
sw-ut-report --input-folder /path/to/files --log-level DEBUG

# Info logging to both console and file
sw-ut-report --input-folder /path/to/files --log-level INFO --log-file /path/to/app.log

# Error logging to file only
sw-ut-report --input-folder /path/to/files --log-level ERROR --log-file /path/to/errors.log

Log File Behavior

• When --log-file is specified, logs are written to both console and file
• File logging always uses DEBUG level for maximum detail
• Console logging uses the level specified by --log-level
• Log files are created if they don't exist
• Existing log files are appended to (not overwritten)

Manual Publishing to PyPI

Note: For a fully automated deployment process, see the next section on using the provided PowerShell script.

To publish this package to PyPI, follow these manual steps:

1. Update the Version

You must update the version number in both of these files:

• src/sw_ut_report/__init__.py (e.g., __version__ = "0.1.0")
• pyproject.toml (e.g., version = "0.1.0")

Make sure the version numbers match in both files. This is required for a successful and consistent release.

2. Build the Package

Install the build tool if you haven't already:

pip install build

Run the following command from the root of the project:

python -m build --no-isolation

This will generate distribution files in the dist/ directory.

3. Prepare for Upload: PyPI Token and .pypirc

• Create an API token on your PyPI account.
• Create a .pypirc file in the root of your repository (but do not commit it to git!).
• The .pypirc file is already listed in .gitignore by default, but always double-check before committing.

Example .pypirc file:

[distutils]
index-servers =
    pypi

[pypi]
username = __token__  # Do not change this value; it must remain exactly as shown
password = <your-pypi-api-token-here>  # Provide your token without any quotes or extra characters

Replace <your-pypi-api-token-here> with your actual PyPI API token.

• Do not add any quotation marks (" or ') or extra characters around the token.
• The line username = __token__ must remain exactly as written.

Important:

• Never share your PyPI token.
• Never commit .pypirc to version control, even if it is already in .gitignore.

4. Upload to PyPI

Install Twine if you haven't already:

pip install twine

Upload your package using Twine and your .pypirc configuration:

twine upload --config-file ./.pypirc dist/*

If successful, your package will be published to PyPI.

Security Reminder

• Keep your PyPI API token secret.
• Do not share your .pypirc file or its contents.
• Always verify you are uploading the correct version and files.

Automated Publishing with PowerShell

You can automate the version update, build, and upload process using the provided PowerShell script:

Prerequisites

• Windows with PowerShell 7 or later
• Python installed and available in your PATH
• .pypirc file present in the project root (see above for details)

Usage

From the project root, run:

pwsh ./publish-to-pypi.ps1 -Version "0.1.2"

Replace 0.1.2 with your desired version number.

What the Script Does

• Checks for the presence of .pypirc and stops if missing
• Installs build and twine if not already installed
• Updates the version in both src/sw_ut_report/__init__.py and pyproject.toml
• Cleans the dist/ directory
• Builds the package
• Uploads the package to PyPI using your .pypirc configuration
• Stops and reports at the first error

This script streamlines the release process and helps ensure consistency between your code and published package.