Metadata-Version: 2.4
Name: pytest-paia-blockly
Version: 0.3.0
Summary: pytest plugin for PAIA Blockly: verify get_solution() against test cases
License: Proprietary
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: loguru>=0.6
Requires-Dist: pydantic>=2.0
Requires-Dist: pytest>=8.0
Description-Content-Type: text/markdown

# pytest-paia-blockly

pytest 外掛，用於 PAIA Blockly：依 `case.json` 測資驗證 `solution.py` 中的 `get_solution()` 是否正確。

---

## 安裝

```bash
pip install pytest-paia-blockly
```

或從原始碼可編輯安裝：

```bash
pip install -e .
# 或
uv pip install -e .
```

---

## 使用方式

### 1. 用 pytest 直接跑（需提供測試檔）

```bash
pytest tests/test_framework.py \
  --paia-target-module ./solution.py \
  --paia-testcases ./case.json \
  --paia-result ./var/result.json \
  -v
```

### 2. 用指令 `paia-blockly-test`（套件內建測試入口）

```bash
paia-blockly-test \
  --paia-target-module ./solution.py \
  --paia-testcases ./case.json \
  --paia-result ./var/result.json \
  -v
```

### 3. 用 `python -m` 執行

```bash
python -m pytest_paia_blockly \
  --paia-target-module ./solution.py \
  --paia-testcases ./case.json \
  --paia-result ./var/result.json \
  -v
```

---

## 命令列選項

| 選項 | 必填 | 說明 |
|------|------|------|
| `--paia-target-module` | 是 | `solution.py` 的檔案路徑，該模組需提供 `get_solution(input: dict)`。 |
| `--paia-testcases` | 是 | `case.json` 的路徑，格式見下方。 |
| `--paia-result` | 否 | 結果 JSON 輸出路徑，預設 `./var/paia_result.json`。 |

選項可用 `--option 值` 或 `--option=值`；建議用空格分隔以利 shell 路徑自動補齊。  
若未提供任一共用選項，`test_verify_case` 會參數化為 0 筆，不會執行任何測資。

---

## 題目格式

- **case.json**：陣列，每筆為 `{ "index", "input", "expected": { "type", "value" } }`。

  ```json
  [
    { "index": 1, "input": { "list": [1, 2] }, "expected": { "type": "int", "value": 3 } },
    { "index": 2, "input": { "list": [3, 4] }, "expected": { "type": "int", "value": 7 } }
  ]
  ```

- **solution.py**：需定義 `get_solution(input: dict)`，回傳值會與 `expected` 比對（型別與值）。

---

## 範例腳本（本 repo）

專案內 `examples/` 為範例題目，可用以下腳本跑對應題目：

| 目錄 | 說明 |
|------|------|
| `scripts/cli/` | 使用 `paia-blockly-test` 的腳本（如 `run_sum_the_list.sh`、`run_all.sh`）。 |
| `scripts/python_m/` | 使用 `python -m pytest_paia_blockly` 的腳本。 |
| `scripts/pytest/` | 使用 `pytest tests/test_framework.py` 的腳本（檔名以 `pytest_` 開頭）。 |

執行前請先啟動虛擬環境或安裝套件，例如：

```bash
bash scripts/cli/run_sum_the_list.sh
# 或
bash scripts/pytest/pytest_sum_the_list.sh
```

---

## 開發

- **測試**：`pytest tests/`（含 `test_plugin.py`、`test_examples.py` 等）。
- **建構與上傳**：`bash scripts/build_and_upload.sh`（需先設定 PyPI token）。

---

## 授權

Copyright (c) 2025 PAIA Technology Inc. All rights reserved.  
詳見 [LICENSE](LICENSE)。
