JTest.Cli 1.0.3

JTest

A powerful JSON-based API testing framework that lets you write comprehensive tests using simple JSON configuration files.

Quick Start

Create your first test file my-test.json:

{
    "version": "1.0",
    "info": {
        "name": "My First Test"
    },
    "env": {
        "testValue": "hello-world"
    },
    "tests": [
        {
            "name": "Basic Variable Test",
            "steps": [
                {
                    "type": "wait",
                    "ms": 100,
                    "assert": [
                        {
                            "op": "equals",
                            "actualValue": "{{$.this.ms}}",
                            "expectedValue": 100
                        }
                    ]
                },
                {
                    "type": "assert",
                    "assert": [
                        {
                            "op": "equals",
                            "actualValue": "{{$.env.testValue}}",
                            "expectedValue": "hello-world"
                        }
                    ]
                }
            ]
        }
    ]
}

Build and run it:

# Clone and build the project
git clone https://github.com/nexxbiz/JTest.git
cd JTest
dotnet build src/JTest.Cli

# Run your test
./src/JTest.Cli/bin/Debug/net8.0/JTest run my-test.json

Or debug the solution:

1. Go to launchsettings.json
2. Replace "<path-to-root-of-project>" with the root path of your project
3. Add or replace any environment variables
4. Run the app with one of the launch profiles "debug tests" or "run tests"

Documentation

📚 Complete Documentation - Start here for comprehensive guides

Quick Links

• Getting Started - Your first test in minutes
• Test Structure - Understanding the JSON format
• HTTP Step - Making HTTP requests
• Assertions - Validating responses
• Templates - Reusable test components
• CLI Usage - Command-line options
• Best Practices - Proven patterns
• Troubleshooting - Debugging help

Key Features

• JSON-Based - Write tests using familiar JSON syntax
• Powerful Assertions - Comprehensive validation with JSONPath expressions
• Template System - Create reusable test components
• Variable System - Environment and global variables with JSONPath access
• Multiple Step Types - HTTP requests, assertions, wait steps, and templates
• CLI Interface - Command-line tool for running and debugging tests
• Extensible - Add custom step types and functionality

Installation

🚀 Quick Setup (Recommended)

One-command installation:

# Linux/macOS
git clone https://github.com/nexxbiz/JTest.git && cd JTest && ./setup.sh

# Windows (PowerShell)  
git clone https://github.com/nexxbiz/JTest.git; cd JTest; .\setup.ps1

This installs the jtest CLI tool globally. After setup:

jtest --help                    # Show help
jtest create "My First Test"    # Create a new test
jtest run my-test.json         # Run tests

📦 Version Management

JTest offers different release channels:

• 🚀 Stable releases: Tagged versions (v1.0.0, etc.) for production use
• 🚧 Development builds: Auto-generated from main branch with latest features

# Use the version manager to download/install specific versions
./scripts/version-manager.sh list                    # List all versions
./scripts/version-manager.sh install development    # Install latest dev build
./scripts/version-manager.sh install latest         # Install latest stable

📦 Other Installation Methods

• Complete Installation Guide - All installation options
• Docker: ./docker.sh build && ./docker.sh run --help
• From Source: dotnet build && ./src/JTest.Cli/bin/Debug/net8.0/JTest --help
• CI/CD Integration: See Installation Guide | GitHub Actions Setup

Usage Examples

Basic Variable and Assertion Test

{
    "version": "1.0",
    "env": {
        "testValue": "hello-world",
        "timeout": 1000
    },
    "globals": {
        "expectedResult": "success"
    },
    "tests": [
        {
            "name": "Variable Test",
            "steps": [
                {
                    "type": "wait",
                    "ms": "{{$.env.timeout}}",
                    "assert": [
                        {
                            "op": "greaterthan",
                            "actualValue": "{{$.this.ms}}",
                            "expectedValue": 500
                        }
                    ]
                },
                {
                    "type": "assert",
                    "assert": [
                        {
                            "op": "equals",
                            "actualValue": "{{$.env.testValue}}",
                            "expectedValue": "hello-world"
                        }
                    ]
                }
            ]
        }
    ]
}

Using Templates

Templates allow you to reuse common patterns. First, create auth-template.json:

{
    "version": "1.0",
    "components": {
        "templates": [
            {
                "name": "authenticate",
                "description": "Generate test authentication token",
                "params": {
                    "username": { "type": "string", "required": true },
                    "password": { "type": "string", "required": true }
                },
                "steps": [],
                "output": {
                    "token": "{{$.username}}-{{$.password}}-token",
                    "authHeader": "Bearer {{$.username}}-{{$.password}}-token"
                }
            }
        ]
    }
}

Then use it in your test:

{
    "version": "1.0",
    "using": ["./auth-template.json"],
    "tests": [
        {
            "name": "Template Usage Example",
            "steps": [
                {
                    "type": "use",
                    "template": "authenticate",
                    "with": {
                        "username": "testuser",
                        "password": "secret123"
                    },
                    "save": {
                        "$.globals.authToken": "{{$.this.token}}"
                    }
                },
                {
                    "type": "assert",
                    "assert": [
                        {
                            "op": "equals",
                            "actualValue": "{{$.globals.authToken}}",
                            "expectedValue": "testuser-secret123-token"
                        }
                    ]
                }
            ]
        }
    ]
}

CLI Commands

# Run tests (using globally installed tool)
jtest run tests.json

# Run multiple test files with wildcards
jtest run tests/*.json

# Run with environment variables
jtest run tests.json --env baseUrl=https://api.example.com

# Validate test files
jtest validate tests.json

# Debug mode with verbose output
jtest debug tests.json

Project Structure

JTest/
├── src/                 # Source code
│   ├── JTest.Core/      # Core framework library
│   ├── JTest.Cli/       # Command-line interface
│   └── JTest.UnitTests/ # Unit tests
└── docs/                # Documentation
    ├── README.md        # Documentation index
    ├── 01-getting-started.md
    ├── 02-test-structure.md
    ├── steps/           # Step type documentation
    ├── templates.md
    ├── assertions.md
    ├── best-practices.md
    ├── cli-usage.md
    ├── troubleshooting.md
    ├── ci-cd-integration.md
    └── extensibility.md

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

See Contributing Guidelines for more details.

License

This project is licensed under the MIT License - see the LICENSE file for details.