je-api-testka 0.0.138

Requests Automation Framework

APITestka

APITestka is a lightweight, cross-platform framework for automated API testing. It supports HTTP/HTTPS, SOAP/XML, and JSON, with high-performance request execution, detailed reporting, and flexible CLI scripting.

Designed for speed and scalability, APITestka enables thousands of requests per second, integrates with mock servers and remote automation, and generates reports in multiple formats for easy analysis.

Translations / Other Languages: 繁體中文 | 简体中文

---

Table of Contents

• Features
• Architecture Overview
• Installation
• Quick Start
  • Using the requests Backend
  • Using the httpx Backend (Sync)
  • Using the httpx Backend (Async)
  • HTTP/2 Support
  • SOAP/XML Request
  • Session-Based Requests
• Result Assertion
• Report Generation
  • HTML Report
  • JSON Report
  • XML Report
• Mock Server
• Callback Executor
• Scripting with Executor
  • JSON Keyword-Driven Testing
  • Executing JSON Files via Python
  • Executing a Directory of JSON Files
  • Adding Custom Commands
• CLI Usage
• Remote Automation (Socket Server)
• Project Scaffolding
• GUI (Optional)
• Test Record
• Project Structure
• Requirements
• Development
• Contributing
• License
• Links

---

Features

Category	Details
HTTP Clients	requests (sync, session support) and httpx (sync + async, HTTP/2)
Protocols	HTTP, HTTPS, SOAP/XML, JSON
Report Formats	HTML, JSON, XML
Scripting	JSON keyword-driven test execution via Executor
Mock Server	Built-in Flask-based mock server for local testing
Remote Automation	TCP socket server for remote command execution
Assertions	Built-in response field assertion (status code, headers, body, etc.)
Callback System	Execute callback functions after API calls
CLI	Full command-line interface for CI/CD integration
Project Scaffolding	Auto-generate project structure with templates
GUI	Optional PySide6 GUI (install with pip install je_api_testka[gui])
Cross-Platform	Windows, macOS, Linux
Performance	Thousands of requests per second

---

Architecture Overview

je_api_testka/
├── requests_wrapper/      # requests-based HTTP client
├── httpx_wrapper/         # httpx-based HTTP client (sync + async)
├── utils/
│   ├── assert_result/     # Response assertion
│   ├── callback/          # Callback function executor
│   ├── executor/          # JSON keyword-driven action executor
│   ├── generate_report/   # HTML / JSON / XML report generation
│   ├── mock_server/       # Flask-based mock server
│   ├── socket_server/     # TCP socket server for remote automation
│   ├── project/           # Project scaffolding & templates
│   ├── json/              # JSON read/write utilities
│   ├── xml/               # XML parse/convert utilities
│   ├── test_record/       # Global test record storage
│   ├── logging/           # Logging instance
│   ├── file_process/      # File listing utilities
│   ├── package_manager/   # Dynamic package loading
│   └── exception/         # Custom exceptions
└── gui/                   # Optional PySide6 GUI

---

Installation

pip install je_api_testka

To install with GUI support:

pip install je_api_testka[gui]

---

Quick Start

Using the requests Backend

from je_api_testka import test_api_method_requests

# GET request
result = test_api_method_requests("get", "http://httpbin.org/get")
print(result["response_data"]["status_code"])  # 200

# POST request with parameters
result = test_api_method_requests(
    "post",
    "http://httpbin.org/post",
    params={"task": "new task"}
)
print(result["response_data"]["status_code"])  # 200

Using the httpx Backend (Sync)

from je_api_testka import test_api_method_httpx

result = test_api_method_httpx("get", "http://httpbin.org/get")
print(result["response_data"]["status_code"])  # 200

Using the httpx Backend (Async)

import asyncio
from je_api_testka import test_api_method_httpx_async

async def main():
    result = await test_api_method_httpx_async("get", "http://httpbin.org/get")
    print(result["response_data"]["status_code"])  # 200

asyncio.run(main())

HTTP/2 Support

import asyncio
from je_api_testka import test_api_method_httpx_async

async def main():
    result = await test_api_method_httpx_async(
        "get",
        "https://httpbin.org/get",
        http2=True
    )
    print(result["response_data"]["status_code"])

asyncio.run(main())

SOAP/XML Request

from je_api_testka import test_api_method_requests

result = test_api_method_requests(
    "post",
    "http://example.com/soap-endpoint",
    soap=True,
    data='<soap:Envelope>...</soap:Envelope>'
)

When soap=True, the Content-Type header is automatically set to application/soap+xml.

Session-Based Requests

The requests backend supports session-based methods for persistent connections (cookies, auth, etc.):

from je_api_testka import test_api_method_requests

# Use session_get, session_post, session_put, session_patch, session_delete, session_head, session_options
result = test_api_method_requests("session_get", "http://httpbin.org/get")

---

Result Assertion

Pass a result_check_dict to automatically assert response fields:

from je_api_testka import test_api_method_requests

# This will raise APIAssertException if status_code is not 200
test_api_method_requests(
    "get",
    "http://httpbin.org/get",
    result_check_dict={"status_code": 200}
)

You can assert on any field in the response data: status_code, text, content, headers, cookies, encoding, elapsed, request_time_sec, request_method, request_url, request_body, start_time, end_time.

---

Report Generation

Reports are generated from the global test_record_instance, which automatically records all test results.

HTML Report

from je_api_testka import test_api_method_requests, generate_html_report

test_api_method_requests("get", "http://httpbin.org/get")
test_api_method_requests("post", "http://httpbin.org/post")

# Generates "my_report.html" with success/failure tables
generate_html_report("my_report")

JSON Report

from je_api_testka import test_api_method_requests, generate_json_report

test_api_method_requests("get", "http://httpbin.org/get")

# Generates "my_report_success.json" and "my_report_failure.json"
generate_json_report("my_report")

XML Report

from je_api_testka import test_api_method_requests, generate_xml_report

test_api_method_requests("get", "http://httpbin.org/get")

# Generates "my_report_success.xml" and "my_report_failure.xml"
generate_xml_report("my_report")

---

Mock Server

APITestka includes a built-in Flask-based mock server for local testing:

from je_api_testka import flask_mock_server_instance, request

# Add custom routes
def my_endpoint():
    return {"message": "hello", "params": dict(request.args)}

flask_mock_server_instance.add_router(
    {"/api/test": my_endpoint},
    methods=["GET", "POST"]
)

# Start the mock server (default: localhost:8090)
flask_mock_server_instance.start_mock_server()

You can also create a new instance with a custom host/port:

from je_api_testka.utils.mock_server.flask_mock_server import FlaskMockServer

server = FlaskMockServer("0.0.0.0", 5000)
server.add_router({"/health": lambda: "OK"}, methods=["GET"])
server.start_mock_server()

---

Callback Executor

Execute a callback function after an API test completes:

from je_api_testka import callback_executor

def my_callback(message):
    print(f"Callback: {message}")

callback_executor.callback_function(
    trigger_function_name="AT_test_api_method",
    callback_function=my_callback,
    callback_function_param={"message": "Test done!"},
    callback_param_method="kwargs",
    http_method="get",
    test_url="http://httpbin.org/get"
)

---

Scripting with Executor

The Executor enables JSON keyword-driven testing, where test actions are defined as JSON arrays and executed programmatically.

JSON Keyword-Driven Testing

Create a JSON file (e.g., test_actions.json):

{
    "api_testka": [
        ["AT_test_api_method", {
            "http_method": "get",
            "test_url": "http://httpbin.org/get",
            "result_check_dict": {"status_code": 200}
        }],
        ["AT_test_api_method", {
            "http_method": "post",
            "test_url": "http://httpbin.org/post",
            "params": {"task": "new task"},
            "result_check_dict": {"status_code": 200}
        }]
    ]
}

Executing JSON Files via Python

from je_api_testka import execute_action, read_action_json

execute_action(read_action_json("test_actions.json"))

Executing a Directory of JSON Files

from je_api_testka import execute_files, get_dir_files_as_list

execute_files(get_dir_files_as_list("path/to/json_dir"))

Adding Custom Commands

from je_api_testka import add_command_to_executor, execute_action

def my_custom_function(url):
    print(f"Custom test on: {url}")

add_command_to_executor({"my_test": my_custom_function})

execute_action([
    ["my_test", ["http://example.com"]]
])

Available built-in Executor commands:

Command	Description
AT_test_api_method	Test API with requests backend
AT_test_api_method_httpx	Test API with httpx sync backend
AT_delegate_async_httpx	Test API with httpx async backend (run synchronously)
AT_generate_html	Generate HTML report data
AT_generate_html_report	Generate HTML report file
AT_generate_json	Generate JSON report data
AT_generate_json_report	Generate JSON report file
AT_generate_xml	Generate XML report data
AT_generate_xml_report	Generate XML report file
AT_execute_action	Execute nested action list
AT_execute_files	Execute actions from multiple files
AT_add_package_to_executor	Dynamically load a package into executor
AT_add_package_to_callback_executor	Dynamically load a package into callback executor
AT_flask_mock_server_add_router	Add route to mock server
AT_start_flask_mock_server	Start mock server

---

CLI Usage

APITestka provides a full CLI interface:

# Execute a single JSON action file
python -m je_api_testka -e test_actions.json

# Execute all JSON files in a directory
python -m je_api_testka -d path/to/json_dir

# Execute a JSON string directly
python -m je_api_testka --execute_str '[["AT_test_api_method", {"http_method": "get", "test_url": "http://httpbin.org/get"}]]'

# Create a new project with templates
python -m je_api_testka -c MyProject

Flag	Description
-e, --execute_file	Execute a single JSON action file
-d, --execute_dir	Execute all JSON files in a directory
--execute_str	Execute a JSON string directly
-c, --create_project	Create a project directory with template files

---

Remote Automation (Socket Server)

APITestka includes a TCP socket server for remote command execution:

from je_api_testka import start_apitestka_socket_server

# Start the socket server (default: localhost:9939)
server = start_apitestka_socket_server(host="localhost", port=9939)

Clients can send JSON-formatted action lists via TCP, and the server will execute them and return results. Send quit_server to shut down the server.

The server also supports CLI arguments:

python -m je_api_testka.utils.socket_server.api_testka_socket_server localhost 9939

---

Project Scaffolding

Generate a project structure with keyword and executor templates:

from je_api_testka import create_project_dir

create_project_dir(project_path=".", parent_name="MyAPIProject")

This creates:

MyAPIProject/
├── keyword/
│   ├── keyword1.json          # Example keyword test (POST)
│   ├── keyword2.json          # Example keyword test (GET)
│   └── bad_keyword_1.json     # Example with package loading
└── executor/
    ├── executor_one_file.py   # Execute a single keyword file
    ├── executor_folder.py     # Execute all keyword files in directory
    └── executor_bad_file.py   # Example with dynamic package loading

---

GUI (Optional)

APITestka provides an optional PySide6-based GUI:

pip install je_api_testka[gui]

The GUI requires PySide6 6.11.0 and qt-material.

---

Test Record

All API test results are automatically stored in a global test_record_instance:

from je_api_testka import test_api_method_requests, test_record_instance

test_api_method_requests("get", "http://httpbin.org/get")
test_api_method_requests("get", "http://invalid-url")

# Access successful test records
print(len(test_record_instance.test_record_list))

# Access error records
print(len(test_record_instance.error_record_list))

# Clean all records
test_record_instance.clean_record()

Each successful record contains: status_code, text, content, headers, history, encoding, cookies, elapsed, request_time_sec, request_method, request_url, request_body, start_time, end_time.

---

Project Structure

APITestka/
├── je_api_testka/             # Main package
│   ├── __init__.py            # Public API exports
│   ├── __main__.py            # CLI entry point
│   ├── requests_wrapper/      # requests HTTP client wrapper
│   ├── httpx_wrapper/         # httpx HTTP client wrapper (sync + async)
│   ├── utils/                 # Utility modules
│   └── gui/                   # Optional PySide6 GUI
├── test/                      # Test suite
│   ├── test_requests/         # Tests for requests backend
│   ├── test_httpx_sync/       # Tests for httpx sync backend
│   ├── test_httpx_async/      # Tests for httpx async backend
│   └── test_utils/            # Tests for utility modules
├── docs/                      # Sphinx documentation source
├── apitestka_driver/          # Standalone driver executables
├── licenses/                  # License files
├── pyproject.toml             # Build configuration
├── requirements.txt           # Runtime dependencies
└── dev_requirements.txt       # Development dependencies

---

Requirements

• Python 3.10 or later
• Dependencies: requests, Flask, httpx
• Optional (GUI): PySide6==6.11.0, qt-material

---

Development

# Clone the repository
git clone https://github.com/Intergration-Automation-Testing/APITestka.git
cd APITestka

# Install development dependencies
pip install -r dev_requirements.txt

# Run tests
pytest

---

Contributing

See CONTRIBUTING.md for guidelines.

---

License

This project is licensed under the MIT License. See licenses/APITestka_LICENSE.

---

Links

• Homepage: https://github.com/Intergration-Automation-Testing/APITestka
• Documentation: https://apitestka.readthedocs.io/en/latest/
• PyPI: https://pypi.org/project/je_api_testka/