# kiwi-tcms-api

Python client for working with [Kiwi TCMS](https://kiwitcms.org/) via JSON-RPC API.

## Installation

```bash
pip install kiwi-tcms-api
```

## Features

- Authenticated connection via session (CSRF + Cookie)
- 4 ways to initialize the client
- Configuration via environment variables
- Full coverage of official API: TestCase, TestRun, TestPlan, TestExecution, Product, Build, User and more
- Two calling styles: named methods and dot-notation (`rpc.Product.filter()`)
- Support for self-signed SSL certificates

## Install Dependencies

```bash
pip install requests beautifulsoup4
```

## Quick Start

```python
from kiwi_tcms_api import KiwiTCMSApi

rpc = KiwiTCMSApi(url='https://tcms.example.com', username='admin', password='secret')

# Get list of products
products = rpc.Product_filter()

# Create a test run
run = rpc.TestRun_create({
    'summary': 'Smoke Tests',
    'plan': 1,
    'build': 1,
    'manager': 1,
})
```

## Initialization Methods

```python
# 1. From environment variables
rpc = KiwiTCMSApi()

# 2. Explicit parameters
rpc = KiwiTCMSApi(url='https://tcms.example.com', username='admin', password='secret')

# 3. Deferred connection
rpc = KiwiTCMSApi.configure(url='https://tcms.example.com', username='admin', password='secret')
rpc.connect()

# 4. From configuration dictionary
cfg = {'url': 'https://tcms.example.com', 'username': 'admin', 'password': 'secret'}
rpc = KiwiTCMSApi.from_config(cfg)
```

## Environment Variables

| Variable                 | Default                | Description                          |
|--------------------------|------------------------|--------------------------------------|
| `KIWI_TCMS_API_URL`      | `http://localhost:8000`| Kiwi TCMS server URL                |
| `KIWI_TCMS_API_USERNAME` | —                      | Username                            |
| `KIWI_TCMS_API_PASSWORD` | —                      | Password                            |
| `KIWI_TCMS_API_VERIFY_SSL`| `true`                 | SSL certificate verification (`false` for self-signed) |

## Method Call Styles

```python
# Named method
rpc.TestCase_filter({'product': 1})

# Dot-notation (module.method)
rpc.TestCase.filter({'product': 1})

# Direct exec call
rpc.exec('TestCase.filter', [{'product': 1}])
```

## API Coverage

| Module               | Methods                                                                                      |
|----------------------|---------------------------------------------------------------------------------------------|
| `Auth`               | login, logout                                                                               |
| `TestCase`           | create, filter, update, remove, add/remove tag/component/attachment/comment/property and more |
| `TestPlan`           | create, filter, update, add/remove case/tag/attachment, tree                                |
| `TestRun`            | create, filter, update, add/remove case/tag/cc/attachment/property                         |
| `TestExecution`      | create, filter, update, add/remove comment/link/attachment/property                         |
| `TestCaseStatus`     | create, filter                                                                              |
| `TestExecutionStatus`| create, filter                                                                              |
| `Product`            | create, filter                                                                              |
| `Build`              | create, filter, update                                                                      |
| `Version`            | create, filter                                                                              |
| `Component`          | create, filter, update                                                                      |
| `Category`           | create, filter                                                                              |
| `Environment`        | create, filter, add/remove property                                                         |
| `User`               | filter, update, deactivate, join_group, add_attachment                                      |
| `Group`              | filter, permissions, users                                                                  |
| `Bug`                | details, report                                                                             |
| `BugTracker`         | create, filter                                                                              |
| `Tag`                | create, filter                                                                              |
| `Template`           | create, filter                                                                              |
| `PlanType`           | create, filter                                                                              |
| `Priority`           | create, filter                                                                              |
| `Classification`     | create, filter                                                                              |
| `Attachment`         | remove_attachment                                                                           |
| `Markdown`           | render                                                                                      |
| `Kiwitcms`           | version                                                                                     |
| `Utils`              | tracker_from_url                                                                            |

## Examples

### Creating a test case and adding to a plan

```python
rpc = KiwiTCMSApi()

case = rpc.TestCase_create({
    'summary': 'Authorization check',
    'product': 1,
    'category': 1,
    'priority': 1,
    'case_status': 2,
})

rpc.TestPlan_add_case(plan_id=5, case_id=case['id'])
```

### Updating execution status

```python
rpc.TestExecution_update(execution_id=42, values={'status': 4})
```

### Adding a link to an execution

```python
rpc.TestExecution_add_link({
    'execution': 42,
    'url': 'https://jira.example.com/browse/BUG-123',
    'name': 'BUG-123',
})
```

### Disabling SSL verification (self-signed certificate)

```python
rpc = KiwiTCMSApi(url='https://tcms.internal', username='admin', password='secret', verify_ssl=False)
# or via environment variable:
# KIWI_TCMS_API_VERIFY_SSL=false
```

### Discovering available methods

```python
rpc.discover_methods()
```
