Metadata-Version: 2.4
Name: testcli-toolkit
Version: 0.2.0
Summary: CLI kiểm thử tự động toàn diện dành cho tester: API test, env, mock server, fake data, seed/reset DB, scaffold framework, hạ tầng test local
Author-email: ptuan21 <bonglongxuyen2k3@gmail.com>
License: MIT
Keywords: testing,qa,cli,automation,api-testing,test-framework
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: requests>=2.31
Requires-Dist: pyyaml>=6.0
Requires-Dist: pydantic>=2.6
Requires-Dist: rich>=13.7
Requires-Dist: jsonpath-ng>=1.6
Requires-Dist: jinja2>=3.1
Requires-Dist: faker>=24.0
Requires-Dist: sqlalchemy>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: responses>=0.25; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# testcli

CLI kiểm thử tự động toàn diện dành cho tester — viết bằng Python, dùng được cả như một câu lệnh CLI lẫn thư viện Python.

Test case khai báo bằng YAML, không cần viết code cho các kịch bản API test cơ bản; đồng thời cung cấp bộ công cụ hỗ trợ xung quanh: quản lý môi trường, mock server, sinh dữ liệu giả, seed/reset database, scaffold dự án cho framework khác, và dựng hạ tầng test local (Selenium Grid, Appium, emulator/simulator).

## Cài đặt

```bash
pip install testcli-toolkit
```

Lệnh CLI sau khi cài là `testcli` (không phải `testcli-toolkit`).

## Bắt đầu nhanh

```bash
testcli init myproject
cd myproject
testcli run tests --env env.yaml
```

Ví dụ test case (`tests/example.yaml`):

```yaml
tests:
  - name: "Lấy thông tin user #1"
    request:
      method: GET
      url: "{{base_url}}/users/1"
    assertions:
      - type: status_code
        expected: 200
      - type: json_path
        path: "$.id"
        expected: 1
    extract:
      user_id: "$.id"
```

## Tính năng

| Nhóm lệnh | Mô tả |
|---|---|
| `run` | Chạy test YAML: filter theo tag, chạy song song (`--parallel`), retry, sharding (`--shard i/n`) cho CI matrix, xuất báo cáo console/JSON/HTML/JUnit XML, ghi lịch sử phát hiện flaky test, gửi thông báo Slack/Teams |
| `env` | Quản lý nhiều môi trường (`envs/<name>.yaml`), chuyển đổi nhanh, healthcheck trước khi chạy test |
| `report` | Gửi tóm tắt kết quả tới Slack/Teams từ báo cáo JSON có sẵn; liệt kê flaky test qua lịch sử chạy |
| `data` | Sinh dữ liệu test giả (Faker: preset user/company/payment hoặc schema tuỳ chỉnh) ra JSON/CSV; seed/reset dữ liệu database thật (SQLAlchemy, đa engine) |
| `mock` | Dựng mock server thật từ đặc tả OpenAPI/Swagger, tự suy response mẫu từ schema |
| `init --template` | Scaffold dự án theo framework khác: Pytest+Allure, Playwright+TypeScript, Cypress, Appium+Java+REST-Assured |
| `infra` | Dựng hạ tầng test local qua Docker Compose (Selenium Grid, Appium server, Postgres/MySQL); liệt kê & khởi động Android emulator / iOS simulator |
| `list` / `validate` | Liệt kê và kiểm tra cú pháp test case |

Xem chi tiết từng lệnh: `testcli --help`, `testcli <nhóm lệnh> --help`.

### Kịch bản phức tạp & quy mô lớn

- **Data-driven test**: 1 test case chạy lặp với nhiều bộ dữ liệu (`data:` inline hoặc `data_file:` trỏ tới CSV/JSON/YAML).
- **Setup/teardown**: khai báo `setup:`/`teardown:` ở cấp file, chạy 1 lần trước/sau các test.
- **Xác thực tự động**: khai báo `auth:` (bearer/basic/`oauth2_client_credentials`) trong env file — tự lấy/refresh token và tiêm header `Authorization` vào mọi request.
- **Custom assertion bằng Python**: `type: custom` trỏ tới `module`/`function` tự viết khi 8 loại assertion có sẵn không đủ.
- **Suite composition**: `include:` kế thừa `defaults` (headers/tags/assertions/suite) dùng chung giữa nhiều file YAML.
- **Sharding**: `--shard i/n` chia suite chạy trên nhiều máy/CI runner, kết hợp `--junit-report` để CI tổng hợp kết quả.
- **Song song mịn hơn**: mặc định `--parallel` nhóm theo file để giữ đúng chuỗi biến `extract`; khai báo `chain: <tên>` trên test để nhóm song song theo ý muốn thay vì theo file.

```yaml
# tests/users.yaml
include:
  - ../fixtures/common.yaml   # kế thừa headers/tags dùng chung

setup:
  - name: "seed dữ liệu"
    request: {method: POST, url: "{{base_url}}/seed"}

tests:
  - name: "tạo user {{email}}"
    data_file: users.csv
    request:
      method: POST
      url: "{{base_url}}/users"
      json: {email: "{{email}}"}
    assertions:
      - type: status_code
        expected: 201
      - type: custom
        module: checks.py
        function: check_password_hashed

teardown:
  - name: "dọn dẹp"
    request: {method: POST, url: "{{base_url}}/cleanup"}
```

## Dùng như thư viện Python

```python
from testcli import Context, TestCase, load_test_suite, run_tests

context = Context.from_env_file("env.yaml")
cases = load_test_suite("tests/")
result = run_tests(cases, context)

print(result.passed_count, result.failed_count)
```

## Assertion hỗ trợ

`status_code`, `json_path`, `json_path_exists`, `response_time`, `body_contains`, `body_regex`, `header`, `header_contains`.

## Phát triển

```bash
git clone <repo-url>
cd testcli
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
```

## License

MIT — xem [LICENSE](LICENSE).
