# TestPyPI パッケージ動作テストガイド

このドキュメントでは、TestPyPIに公開したパッケージの動作をローカルで検証する方法を説明します。

## 概要

パッケージをTestPyPIに公開した後、本番環境でのリリース前に、隔離されたローカル環境で正常に動作することを確認する必要があります。
このガイドでは、複数の隔離環境を使用した検証方法を提供します。

:::{admonition} 目的

開発環境の汚染を避けつつ、TestPyPIで公開されたパッケージの動作を完全に検証する

:::

## クイックスタート

最小限の検証を迅速に行いたい場合

```bash
# 1. 仮想環境を作成
python3 -m venv /tmp/test-env
source /tmp/test-env/bin/activate

# 仮想環境が有効になるとプロンプトに (test-env) と表示
# (test-env) $

# 2. TestPyPIからインストール
(test-env) $ pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ haniwers

# 3. インストール確認
(test-env) $ haniwers version

# 4. 基本的な動作確認
(test-env) $ haniwers --help

# 5. 終了
(test-env) $ deactivate
$ rm -rf /tmp/test-env
```

## セットアップ方法

### 方法1: Python標準の `venv`（推奨・シンプル）

**利点:**

- 外部ツール不要
- セットアップが簡単
- 開発環境に影響なし

**手順:**

```bash
# 1. 仮想環境を作成
python3 -m venv /tmp/test-env

# 2. 仮想環境をアクティベート
source /tmp/test-env/bin/activate  # macOS/Linux
# または
/tmp/test-env/Scripts/activate  # Windows

# 仮想環境が有効になるとプロンプトに (test-env) と表示
# (test-env) $

# 3. pipをアップグレード
(test-env) $ pip install --upgrade pip

# 4. TestPyPIからインストール
(test-env) $ pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    haniwers

# 5. インストール確認
(test-env) $ pip list

# 6. テスト完了後、終了
(test-env) $ deactivate

# 仮想環境が無効になるとプロンプトが通常に戻る
# $

# 7. 環境を削除（オプション）
$ rm -rf /tmp/test-env
```

**パスの説明:**

- `/tmp/test-env`: テンポラリディレクトリに環境を作成（終了後も一定期間の保持が可能）
- または `~/test-test` などローカルに作成してもよい

### 方法2: `uv` を使用（高速・モダン）

**利点:**

- 非常に高速
- 複数Python版の管理が容易
- Poetry と共存可能

**セットアップ:**

```bash
# uv をインストール（まだの場合）
curl -LsSf https://astral.sh/uv/install.sh | sh

# または pipx で
pipx install uv
```

**使用方法:**

```bash
# 1. 仮想環境を作成（任意のPythonバージョン指定可能）
uv venv /tmp/test-env --python 3.11

# 2. アクティベート
source /tmp/test-env/bin/activate

# 仮想環境が有効になるとプロンプトに (test-env) と表示
# (test-env) $

# 3. TestPyPIからインストール
(test-env) $ uv pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    haniwers

# 4. インストール確認
(test-env) $ uv pip list

# 5. 終了
(test-env) $ deactivate
```

**複数Pythonバージョンでのテスト:**

```bash
# Python 3.11 環境でテスト
uv venv /tmp/testpypi-3.11 --python 3.11
source /tmp/testpypi-3.11/bin/activate

# (testpypi-3.11) $
(testpypi-3.11) $ uv pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    haniwers
(testpypi-3.11) $ haniwers version
(testpypi-3.11) $ deactivate

# Python 3.12 環境でテスト
uv venv /tmp/testpypi-3.12 --python 3.12
source /tmp/testpypi-3.12/bin/activate

# (testpypi-3.12) $
(testpypi-3.12) $ uv pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    haniwers
(testpypi-3.12) $ haniwers version
(testpypi-3.12) $ deactivate
```

## パッケージの動作テスト

### 1. インストール確認

```bash
# インストール済みパッケージを確認
(test-env) $ pip show haniwers

# 出力例
# Name: haniwers
# Version: 1.4.0
# Summary: Cosmic ray detection analysis tool
# Location: /path/to/venv/lib/python3.11/site-packages
```

### 2. CLI動作確認

```bash
# 仮想環境内で実行（プロンプトに環境名が表示されている状態）
(test-env) $ haniwers version

# 詳細な環境情報
(test-env) $ haniwers version --env

# ヘルプ表示
(test-env) $ haniwers --help

# サブコマンド確認
(test-env) $ haniwers-v0 --help
(test-env) $ haniwers-v1 --help
```

### 3. 基本コマンドテスト

```bash
# 仮想環境内で実行
# ポート一覧表示（ハードウェア接続不要）
(test-env) $ haniwers-v1 port list

# モックデバイスでDAQテスト
(test-env) $ haniwers-v1 daq --help

# 設定ファイル機能テスト
(test-env) $ haniwers-v1 config --help
```

### 4. Pythonモジュールテスト

```bash
# 仮想環境内で実行
# Pythonコードでモジュール導入可能か確認
(test-env) $ python3 -c "import haniwers; print(haniwers.__version__)"

# v0モジュール確認
(test-env) $ python3 -c "from haniwers.v0 import cli; print('v0 imported')"

# v1モジュール確認
(test-env) $ python3 -c "from haniwers.v1 import cli; print('v1 imported')"
```

### 5. 依存関係確認

```bash
# 仮想環境内で実行
# インストール済み依存パッケージを確認
(test-env) $ pip list

# 特定パッケージの確認（例：typer）
(test-env) $ pip show typer
(test-env) $ pip show pydantic
```

## トラブルシューティング

### インストール失敗：「Package not found」

**原因:** TestPyPIに公開されていない、またはバージョン番号が間違っている

**対処:**

```bash
# TestPyPIのパッケージページを確認
# https://test.pypi.org/project/haniwers/

# 最新版のバージョン番号を確認
pip index versions --index-url https://test.pypi.org/simple/ haniwers

# 具体的なバージョンを指定してインストール
pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    haniwers==1.4.0
```

### インストール失敗：依存パッケージの解決エラー

**原因:** 依存関係が PyPI に存在しない

**対処:**

```bash
# 詳細なエラーメッセージを確認
pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    -v haniwers

# キャッシュをクリアして再試行
pip cache purge
pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    haniwers
```

### インストール成功したがコマンドが見つからない

**原因:** 仮想環境が正しくアクティベートされていない、または PATH が設定されていない

**対処:**

```bash
# 仮想環境をアクティベート（再度実行）
source /tmp/test-env/bin/activate

# which コマンドで確認
(test-env) $ which haniwers
(test-env) $ which haniwers-v1

# フルパスで実行
(test-env) $ /tmp/test-env/bin/haniwers --help
```

### 古いバージョンがインストールされてしまう

**原因:** pip のキャッシュが古い、またはシステムワイドのインストール版が干渉している

**対処:**

```bash
# キャッシュをクリア
(test-env) $ pip cache purge

# 既存インストール削除
(test-env) $ pip uninstall haniwers -y

# 再度インストール
(test-env) $ pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    haniwers --no-cache-dir
```

### ImportError: No module named 'haniwers'

**原因:** Python が仮想環境を使用していない、またはインストールが不完全

**対処:**

```bash
# 仮想環境内の Python を使用
source /tmp/test-env/bin/activate

# 仮想環境内の Python で実行
(test-env) $ /tmp/testpypi-env/bin/python -c "import haniwers; print(haniwers.__version__)"

# 再インストール
(test-env) $ pip uninstall haniwers -y
(test-env) $ pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    haniwers
```

## 複数環境での並行テスト

同じマシンで複数の隔離環境を使用する場合：

```bash
# テスト環境リスト
/tmp/testpypi-env-3.11  # Python 3.11用
/tmp/testpypi-env-3.12  # Python 3.12用
/tmp/testpypi-env-dev   # 開発版テスト用

# 環境1でテスト実行
source /tmp/testpypi-env-3.11/bin/activate
(testpypi-env-3.11) $ haniwers version
(testpypi-env-3.11) $ deactivate

# 環境2でテスト実行
source /tmp/testpypi-env-3.12/bin/activate
(testpypi-env-3.12) $ haniwers version
(testpypi-env-3.12) $ deactivate

# 結果を記録
echo "Python 3.11: $(source /tmp/testpypi-env-3.11/bin/activate && haniwers version)"
echo "Python 3.12: $(source /tmp/testpypi-env-3.12/bin/activate && haniwers version)"
```

## 環境のクリーンアップ

テスト完了後の環境削除：

```bash
# 仮想環境をアクティベート解除
deactivate

# ディレクトリを削除
rm -rf /tmp/testpypi-env

# 複数環境がある場合
rm -rf /tmp/testpypi-env-*

# pip キャッシュをクリア（オプション）
pip cache purge
```

## ベストプラクティス

### 1. 環境名を記述的につける

```bash
# 良い例
/tmp/testpypi-haniwers-1.4.0-py311
/tmp/testpypi-haniwers-1.4.0-py312

# 悪い例
/tmp/test
/tmp/env
```

### 2. テスト結果を記録する

```bash
# テスト結果をログファイルに保存
{
  echo "=== TestPyPI Package Test Log ==="
  echo "Date: $(date)"
  echo "Package: haniwers"

  source /tmp/testpypi-env/bin/activate
  echo "Version: $(haniwers version)"
  echo "Environment:"
  haniwers version --env
  echo ""
  echo "CLI Tests:"
  haniwers --help
  deactivate
} > /tmp/testpypi-test-results.log

# ログファイルの内容を表示
$ cat /tmp/testpypi-test-results.log
```

### 3. テストスクリプトを自動化する

```bash
#!/bin/bash
# test-testpypi.sh - TestPyPI パッケージテストスクリプト

VERSION=${1:-latest}
ENV_PATH="/tmp/testpypi-env-${VERSION}"

echo "Creating test environment: $ENV_PATH"
python3 -m venv "$ENV_PATH"

source "$ENV_PATH/bin/activate"

# 仮想環境がアクティベートされていることを表示
echo "Virtual environment activated: $ENV_PATH"
echo "Prompt will show: ($ENV_PATH) $"

pip install --upgrade pip

echo "Installing haniwers from TestPyPI..."
pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    haniwers

echo "Running tests..."
haniwers version
haniwers --help
haniwers-v1 port list

deactivate

echo "Test completed. Environment: $ENV_PATH"
echo "To clean up: rm -rf $ENV_PATH"
```

**実行方法:**

```bash
$ chmod +x test-testpypi.sh
$ ./test-testpypi.sh 1.4.0
```

### 4. 検証チェックリスト

テスト時には以下の項目を確認してください：

- [ ] インストールが成功した
- [ ] `haniwers version` でバージョンが表示される
- [ ] `haniwers --help` でコマンド一覧が表示される
- [ ] `haniwers-v0 --help` が動作する
- [ ] `haniwers-v1 --help` が動作する
- [ ] `haniwers-v1 port list` が動作する
- [ ] Python モジュールとしてインポート可能 (`import haniwers`)
- [ ] 依存パッケージがすべてインストールされている (`pip list` で確認)
- [ ] 既存の開発環境に影響がない（別の仮想環境で実行）

## 関連ドキュメント

- [テストガイドライン](./testing.md) - ユニットテストの書き方と実行方法
- [貢献ガイド](./contributing.md) - パッケージリリース前の準備
- [CLI開発ガイド](./cli-development.md) - CLI コマンドの追加・変更
- [アーキテクチャ](./architecture.md) - プロジェクト構成の理解