ATC - API Automation Testing Command Line Tool

Language: 中文文档 | English

ATC (API Test Command) is a powerful API automation testing command-line tool designed to simplify API testing workflows. It supports intelligent test case generation, batch interface testing, multiple data format processing, and more.

✨ Core Features

🎯 Intelligent Test Case Generation

Local Generation: Rapidly generate diverse test cases based on positive examples
Smart Constraint System: Supports 11 constraint types, generating realistic and valid Chinese test data
Multi-format Support: Supports JSON and XML input/output formats
Data Variation Rules: 50% fluctuation for numbers, 10% length change for strings

🤖 AI-Powered Generation

LLM API Integration: Generate intelligent test cases through LLM API
Configuration File Support: Read API settings from config.toml files
Multiple Input Methods: Support command-line input and file input
Streaming Response: Real-time generation progress display
Smart Parsing: Automatically parse API responses and generate test cases

🚀 Batch Interface Testing

Multiple HTTP Methods: Supports POST, GET, and other HTTP request methods
Multiple Authentication: Bearer Token, Basic Auth, API Key, etc.
Custom Headers: Flexible addition of HTTP header information
Concurrent Execution: Improves testing execution efficiency
Result Export: Supports CSV format result export

🛡️ Configuration Validation

Format Validation: Constraint configuration file integrity checking
Content Validation: Data type and range reasonableness validation
Error Reporting: Detailed error information and precise location identification

📦 Installation

System Requirements

Important: This tool uses emoji characters (✅, ❌, 🔍, etc.) in its output for better user experience. To display these characters correctly, your terminal environment must support UTF-8 encoding.

Windows: Use Windows Terminal, PowerShell Core, or enable UTF-8 support in Command Prompt
macOS/Linux: Most modern terminals support UTF-8 by default
SSH/Remote: Ensure your SSH client and server both support UTF-8 encoding

If emoji characters are not displayed correctly, please check your terminal's encoding settings.

Pre-compiled Binary Files

Download the pre-compiled version suitable for your system from the Releases page:

Windows (amd64): atc-windows-amd64.exe
macOS (ARM): atc-darwin-arm64
Linux (ARM): atc-linux-arm64
Linux (amd64): atc-linux-amd64

Compile from Source

# Clone repository
git clone https://github.com/morsuning/ai-auto-test-cmd.git
cd ai-auto-test-cmd

# Quick local build (for development)
go build -o atc

# Or use build scripts with version injection
# Local build with version
./build/build-local.sh v1.0.0

# Cross-platform build with version
./build/build.sh v1.0.0

# Check version after build
./atc --version
./atc version

🚀 Quick Start

1. AI-Powered Test Case Generation

# Use default configuration file to generate test cases
atc llm-gen -c config.toml

# Specify configuration file to generate test cases
atc llm-gen -c my-config.toml -n 3

# Override positive message from config file with command line
atc llm-gen -c config.toml --json '{"name":"test"}' --debug

# Use custom prompt file to generate test cases
atc llm-gen -c config.toml --prompt custom_prompt.txt -n 3

# Combine configuration file and prompt file
atc llm-gen -c my-config.toml --prompt prompt.txt -n 5

# Explicitly specify API parameters (override config file)
atc llm-gen -u https://api.llm.ai/v1 --api-key your_key --xml "<test/>" -n 2

2. Generate Test Cases Locally

# Generate test cases from JSON positive example
atc local-gen --json '{"name":"John","age":25,"email":"test@example.com"}' -n 10

# Generate test cases from XML positive example
atc local-gen --xml '<user><name>John</name><age>25</age></user>' -n 5

# Use configuration file with positive message and test case settings
atc local-gen -c config.toml

# Override positive message from config file with command line
atc local-gen -c config.toml --json '{"name":"test"}' -n 20

# Generate using smart constraint system
atc local-gen -c config.toml -n 10

3. Execute Interface Testing

# POST request sending JSON data
atc request -u https://api.example.com/users -m post -f testcases.csv --json

# GET request
atc request -u https://api.example.com/users -m get -f testcases.csv --json

# Use Bearer Token authentication
atc request -u https://api.example.com/users -m post -f testcases.csv --json --auth-bearer "your_token"

# Add custom request headers
atc request -u https://api.example.com/users -m post -f testcases.csv --json --header "X-API-Key: key123"

# Save test results
atc request -u https://api.example.com/users -m post -f testcases.csv --json -s results.csv

4. Validate Constraint Configuration

# Validate default configuration file
atc validate

# Validate specified configuration file
atc validate my-constraints.toml

# Show detailed validation information
atc validate --verbose

📋 Command Reference

`llm-gen` - AI-Powered Test Case Generation

Generate intelligent test cases through LLM API.

atc llm-gen [flags]

Main Parameters:

--url, -u: LLM API URL (optional, can be read from config file)
--api-key: LLM API Key (optional, can be read from config file)
--config, -c: Configuration file path (default: config.toml)
--json 'content': Specify JSON format and content
--xml 'content': Specify XML format and content
--prompt: Custom prompt file path (optional, file must be UTF-8 encoded)
--num, -n: Generation count (default 5)
--output, -o: Output file path
--debug, -d: Enable debug mode

Configuration File Support:

Create a config.toml file:

[llm]
url = "https://api.llm.ai/v1/chatflows/xxx/run"
api_key = "app-xxxxxxxxxx"

[testcase]
num = 10
output = "test_cases.csv"
type = "json"
positive_example = '''
{
  "user": {
    "name": "John",
    "age": 25,
    "email": "john@example.com"
  }
}
'''

Parameter Priority:

Command-line parameters (highest priority)
Configuration file parameters
Error if neither is specified

Examples:

# Use default configuration file
atc llm-gen -c config.toml

# Specify configuration file
atc llm-gen -c my-config.toml -n 5

# Override config file parameters
atc llm-gen -c config.toml --api-key new_key --json '{"name":"test"}' -n 2

# Override positive message and enable debug
atc llm-gen -c config.toml --xml "<test/>" -n 3 --debug

`local-gen` - Local Test Case Generation

Generate diverse test cases based on positive examples.

atc local-gen [positive_example] [flags]

Main Parameters:

--json: Specify JSON format
--xml: Specify XML format
--num, -n: Generation count (default 10)
--output, -o: Output file path
--config, -c: Specify configuration file path (contains constraint configuration and other settings)

Examples:

# Generate 10 JSON test cases
atc local-gen --json '{"name":"John","age":25}' -n 10

# Use constraint system to generate realistic data
atc local-gen -c config.toml -n 5

# Override positive message from config file
atc local-gen -c config.toml --json '{"name":"张三","phone":"13800138000"}' -n 20 -o testcases.csv

`request` - Batch Interface Testing

Execute HTTP requests in batches based on CSV test case files.

atc request -u [URL] -m [METHOD] -f [CSV_FILE] [flags]

Main Parameters:

--url, -u: Target interface URL (required)
- Note: If URL doesn't include protocol (http:// or https://), http:// will be added automatically
- Example: localhost:8080/user becomes http://localhost:8080/user
--method, -m: HTTP method (post/get)
--file, -f: CSV test case file (required)
--json: JSON format request body
--xml: XML format request body
--save, -s: Save results to file
--timeout: Request timeout (default 30 seconds)
--debug: Enable debug mode

Authentication Parameters:

--auth-bearer: Bearer Token authentication
--auth-basic: Basic Auth authentication (format: username:password)
--header: Custom HTTP headers (can be used multiple times)

Examples:

# Basic POST request
atc request -u https://api.example.com/users -m post -f users.csv --json

# Local server (automatically adds http:// protocol)
atc request -u localhost:8080/api/test -m post -f users.csv --json

# Use authentication and custom headers
atc request -u https://api.example.com/users -m post -f users.csv --json \
  --auth-bearer "eyJhbGciOiJIUzI1NiIs..." \
  --header "X-Request-ID: 12345" \
  --header "X-Client-Version: 1.0"

# GET request (automatically converts to query parameters)
atc request -u https://api.example.com/users -m get -f users.csv --json

# Enable debug mode and save results
atc request -u https://api.example.com/users -m post -f users.csv --json --debug -s results.csv

`validate` - Configuration Validation

Validate the format and content correctness of constraint configuration files.

atc validate [config_file] [flags]

Main Parameters:

--verbose, -v: Show detailed validation information

Examples:

# Validate default configuration
atc validate

# Validate specified configuration file
atc validate my-constraints.toml

# Show detailed information
atc validate --verbose

🎯 Smart Constraint System

The smart constraint system is ATC's core feature, capable of automatically identifying field names and generating realistic and valid test data.

Constraint System Switch

The constraint system supports flexible on/off control through configuration files:

Switch Configuration: [constraints].enable
Switch Behavior:
- true: Enable constraint system, use smart constraint mode to generate test data
- false: Disable constraint system, use random variation mode to generate test data
- Not set: Automatically decide based on whether constraint configuration exists (enable if constraint configuration exists, otherwise disable)

Supported Constraint Types

Constraint Type	Description	Example Field Names	Generation Example
`keep_original`	Keep original value	Any field	(unchanged)
`date`	Date type	date, time, created_at	20230101
`datetime`	DateTime type	datetime, create_datetime	2024-11-22T15:00:26.431Z
`chinese_name`	Chinese name	name, username, author	周桂兰
`phone`	Phone number	phone, mobile, tel	17234495798
`email`	Email address	email, mail	test473@189.cn
`chinese_address`	Chinese address	address, location	武汉市武昌区中南路99号
`id_card`	ID card number	id_card, identity	500101198909148195
`integer`	Integer type	age, count, quantity	64
`float`	Float type	price, amount, rate	161782.59

Configuration File Example

Create a config.toml file:

[testcase]
# Test case settings
num = 10
output = "test_cases.csv"

# Constraint system configuration
[constraints]
# Constraint system switch (true: enable, false: disable)
enable = true

# Date field constraint
[constraints.date]
type = "date"
format = "20060102"  # Go time format
min_date = "20200101"
max_date = "20301231"
description = "Date field, format YYYYMMDD"

# Name field constraint
[constraints.name]
type = "chinese_name"
description = "Chinese name"

# Age field constraint
[constraints.age]
type = "integer"
min = 1
max = 120
description = "Age range 1-120"

# Price field constraint
[constraints.price]
type = "float"
min = 0.01
max = 999999.99
precision = 2
description = "Price field, 2 decimal places"

# Built-in datasets
[constraints.builtin_data]
first_names = ["张", "王", "李", "赵", "刘"]
last_names = ["伟", "芳", "娜", "敏", "静"]
addresses = ["北京市朝阳区建国门外大街1号", "上海市浦东新区陆家嘴环路1000号"]
email_domains = ["qq.com", "163.com", "126.com", "gmail.com"]

Custom Types & Datasets

Define reusable value pools and rules under constraints.types, and reference inline values, custom datasets, or built-in datasets, optionally filtered by a regex pattern.

[constraints]
enable = true

# Declare custom types (support values / dataset / pattern)
[constraints.types.status_text]
values = ["pending", "paid", "shipped", "cancelled"]
description = "Order status text"

[constraints.types.region_code]
dataset = "region_codes"           # from constraints.datasets below
pattern = "^[A-Z]{2}-\\d{2}$"     # filter values by regex
description = "Region code"

# Reference built-in dataset as a custom type source
[constraints.types.email_domain_custom]
dataset = "email_domains"           # from built-in datasets
description = "Email domains (built-in)"

# Declare custom datasets for custom types to reference
[constraints.datasets]
region_codes = ["CN-01", "CN-02", "US-01", "US-02", "JP-01", "DE-01"]

# Apply custom types to fields
[constraints.order.status_text]
type = "status_text"

[constraints.user.region]
type = "region_code"

[constraints.user.email_domain]
type = "email_domain_custom"

Notes:

Pattern compilation is validated during atc validate, but value matching happens at generation time; invalid patterns are ignored safely.
Unknown datasets are skipped; generation falls back to values if present.
If both values and dataset are empty, the original field value is preserved.
Use atc validate -v to see counts and names of custom types and datasets.

Composite Constraints

Use composite constraints to enforce correlated values across multiple fields (e.g., province with city). A single row from data is chosen per test case and applied consistently across all matching fields.

Example：

[constraints]
enable = true

[constraints.composite_address]
type = "composite"
fields = ["province", "city"]
data = [["上海", "上海市"], ["北京", "北京市"], ["广东", "广州市"]]
description = "Province and city must be chosen together"

Behavior：

Select one data row per test case, then override all matching fields.
Matches by the last segment of the field path; works in nested objects and array elements.
Field name normalization: lowercase and - → _ (e.g., city-name ≈ city_name).

Validation：

fields must be non-empty and unique; data must be non-empty.
Each data row length must equal the number of fields.
Invalid configs are reported by atc validate with detailed errors.

Notes：

Within a single test case, all occurrences of composite fields use the same chosen pair/group to preserve consistency.
Composite overrides apply to basic leaf fields; under keep_original on a parent object, child fields still honor composite overrides but otherwise keep their original values.

Generation Effect Comparison

Before using constraint system (random variation):

{"date":"27388202","name":"p","age":18,"phone":"11684695289","email":"1haDgsai8xOmpyU.C0m","price":122,"address":"K京w区"}

After using constraint system (smart constraints):

{"date":"20230101","name":"周桂兰","age":64,"phone":"17234495798","email":"test473@189.cn","price":161782.59,"address":"武汉市武昌区中南路99号"}

📁 CSV File Format

Generation Phase Format

JSON Format: Single-column CSV with column name "JSON", one JSON string per row
XML Format: Single-column CSV with column name "XML", one XML string per row

Testing Phase Format Recognition

Single-column JSON: Column name "JSON", directly uses JSON content as request body
Single-column XML: Column name "XML", directly uses XML content as request body
Multi-column Format: Combines column data into JSON object
GET Requests: Only supports JSON format, automatically converts to query parameters

🔧 Advanced Features

Debug Mode

Use the --debug parameter to enable detailed debug output:

atc request -u https://api.example.com/users -m post -f users.csv --json --debug

Debug mode displays:

Detailed information for each request (URL, method, headers, request body)
Complete response information (status code, response time, response body)
Formatted JSON response content

Concurrency Control

The system automatically adjusts concurrency based on the number of test cases, improving execution efficiency while avoiding excessive pressure on target servers.

Error Handling

Detailed error information prompts
Batch error reporting
Precise error location identification
User-friendly prompts

XML Encoding Support

Important Note: Go's standard library XML processing package (encoding/xml) has limitations regarding XML document encoding:

UTF-8 Only: The standard library can only correctly parse UTF-8 encoded XML documents
Other Encodings Not Supported: XML documents with GBK, GB2312, ISO-8859-1, or other non-UTF-8 encodings cannot be directly processed by the standard library
Encoding Declaration Ignored: Even if an XML document declares <?xml version="1.0" encoding="GBK"?>, the standard library will still process it as UTF-8

ATC's Solution:

Automatic Encoding Detection: Uses golang.org/x/text/encoding package to detect the actual encoding of XML documents
Encoding Conversion: Automatically converts non-UTF-8 encoded XML documents to UTF-8 before parsing
Supported Encoding Formats:
- UTF-8 (native support)
- GBK/GB2312 (Chinese encoding)
- ISO-8859-1 (Western European encoding)
- Other common encoding formats

Usage Recommendations:

Prefer UTF-8 Encoding: For optimal performance and compatibility, use UTF-8 encoded XML documents
Non-UTF-8 Encoding Handling: The tool automatically handles non-UTF-8 encodings, but there may be slight performance overhead
Encoding Declaration Consistency: Ensure XML document encoding declarations match the actual file encoding to avoid parsing errors

📊 Example Project

The examples/ directory contains complete usage examples:

config.toml: Configuration file example (includes constraint configuration)
json_example.json: JSON positive example input
xml_example.xml: XML positive example input
input.xml: Complex XML structure example

🤝 Contributing

Welcome to submit Issues and Pull Requests!

Fork this repository
Create a feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📄 License

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

🔗 Related Links

ATC - Making API testing simpler, smarter, and more efficient!

Name		Name	Last commit message	Last commit date
Latest commit History 62 Commits
.github/workflows		.github/workflows
build		build
cmd		cmd
docs		docs
examples		examples
models		models
test_cases		test_cases
utils		utils
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
README_zh.md		README_zh.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go

Folders and files

Latest commit

History

Repository files navigation

ATC - API Automation Testing Command Line Tool

✨ Core Features

🎯 Intelligent Test Case Generation

🤖 AI-Powered Generation

🚀 Batch Interface Testing

🛡️ Configuration Validation

📦 Installation

System Requirements

Pre-compiled Binary Files

Compile from Source

🚀 Quick Start

1. AI-Powered Test Case Generation

2. Generate Test Cases Locally

3. Execute Interface Testing

4. Validate Constraint Configuration

📋 Command Reference

llm-gen - AI-Powered Test Case Generation

local-gen - Local Test Case Generation

request - Batch Interface Testing

validate - Configuration Validation

🎯 Smart Constraint System

Constraint System Switch

Supported Constraint Types

Configuration File Example

Custom Types & Datasets

Composite Constraints

Generation Effect Comparison

📁 CSV File Format

Generation Phase Format

Testing Phase Format Recognition

🔧 Advanced Features

Debug Mode

Concurrency Control

Error Handling

XML Encoding Support

📊 Example Project

🤝 Contributing

📄 License

🔗 Related Links

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 7

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`llm-gen` - AI-Powered Test Case Generation

`local-gen` - Local Test Case Generation

`request` - Batch Interface Testing

`validate` - Configuration Validation

Packages