{"id":28882342,"url":"https://github.com/0xkaz/kotoba","last_synced_at":"2026-04-29T14:06:37.640Z","repository":{"id":300054190,"uuid":"1004679581","full_name":"0xkaz/kotoba","owner":"0xkaz","description":"kotoba (言葉) - Natural language web testing tool with LLM. Write tests in English/Japanese/Chinese.","archived":false,"fork":false,"pushed_at":"2025-06-19T16:02:21.000Z","size":447,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-19T17:19:43.388Z","etag":null,"topics":["automation","e2e-testing","japanese","llm","multilingual","natural-language","playwright","test-automation","testing","web-testing"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0xkaz.png","metadata":{"files":{"readme":"README.ja.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-19T02:40:13.000Z","updated_at":"2025-06-19T16:02:24.000Z","dependencies_parsed_at":"2025-06-19T17:29:57.037Z","dependency_job_id":null,"html_url":"https://github.com/0xkaz/kotoba","commit_stats":null,"previous_names":["0xkaz/kotoba"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/0xkaz/kotoba","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xkaz%2Fkotoba","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xkaz%2Fkotoba/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xkaz%2Fkotoba/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xkaz%2Fkotoba/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0xkaz","download_url":"https://codeload.github.com/0xkaz/kotoba/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xkaz%2Fkotoba/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32428638,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T13:34:34.882Z","status":"ssl_error","status_checked_at":"2026-04-29T13:34:29.830Z","response_time":110,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","e2e-testing","japanese","llm","multilingual","natural-language","playwright","test-automation","testing","web-testing"],"created_at":"2025-06-20T21:01:22.303Z","updated_at":"2026-04-29T14:06:37.635Z","avatar_url":"https://github.com/0xkaz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kotoba - 自然言語Webテストツール\n\n![kotoba - Natural Language Web Testing](./og_image.png)\n\n**kotoba**は、LLMとPlaywrightを組み合わせた多言語対応の自然言語Webテストツールです。\n\n日本語、中国語、英語の自然言語指示でWebサイトを自動操作できます。\n\n**ドキュメント**: [English](README.md) | [日本語](README.ja.md) | [中文](README.zh-CN.md)\n\n## 特徴\n\n- 🗾 **日本語対応**: 日本語の自然言語指示でWebテストを実行\n- ✅ **テストアサーション**: 100%成功率の日本語自然言語による包括的検証機能\n- 🤖 **LLM統合**: Hugging Face の多様なモデルをサポート\n- 🚀 **軽量設計**: 1.1B〜13Bまでのモデルサイズに対応\n- 🔧 **柔軟な実行**: Dockerとローカル両方に対応\n- 🎯 **MockLLMモード**: LLMモデルなしでも動作確認可能\n- 💾 **効率的キャッシュ**: モデルの永続キャッシュで高速起動\n\n## クイックスタート\n\n### 選択肅2つのインストール方法\n\n#### A. ローカルインストール（推奨）\n\n```bash\n# リポジトリクローン\ngit clone \u003crepository-url\u003e\ncd kotoba\n\n# ローカルインストール\nmake install-local\n\n# 実行\nkotoba --help\n```\n\n#### B. Docker環境（選択胥）\n\n```bash\n# リポジトリクローン\ngit clone \u003crepository-url\u003e\ncd kotoba\n\n# Docker環境構築\nmake build\nmake up\n```\n\n### 2. モデル事前ダウンロード（任意）\n\n```bash\n# デフォルトモデル（日本語特化、3.6B）\nmake download-model MODEL=rinna/japanese-gpt-neox-3.6b\n\n# 軽量モデル（多言語、1.5B）\nmake download-model MODEL=Qwen/Qwen2-1.5B-Instruct\n\n# ※MockLLMモードではモデル不要\n```\n\n### 3. テスト実行\n\n#### ローカル実行\n```bash\n# 開発モードで実行\nmake dev-local\n\n# 直接実行\nkotoba --config configs/dev.yaml --test-file tests/yahoo_japan_test.yaml\nkotoba --help\n\n# MockLLMモードで実行（LLMモデル不要）\nUSE_MOCK_LLM=true kotoba --test-file tests/mock_test.yaml\n```\n\n#### Docker実行\n```bash\n# 開発モードで実行\nmake dev\n\n# カスタム設定で実行\nmake run ARGS=\"--config configs/custom.yaml --test-file tests/github_test.yaml\"\n```\n\n## テストファイルの例\n\n### 基本テスト\n```yaml\n# tests/yahoo_japan_test.yaml\nname: \"Yahoo! Japan検索テスト\"\nbase_url: \"https://www.yahoo.co.jp\"\ntest_cases:\n  - name: \"基本検索テスト\"\n    steps:\n      - instruction: \"検索ボックスに「天気予報」と入力する\"\n      - instruction: \"検索ボタンをクリックする\"\n      - instruction: \"検索結果が表示されるまで待つ\"\n```\n\n### アサーション機能\n\nkotobaは日本語自然言語による包括的なテスト検証機能を提供し、**100%成功率**を達成しています。\n\n```yaml\nname: \"アサーションテスト例\"\nbase_url: \"https://example.com\"\ntest_cases:\n  - name: \"基本的な検証\"\n    description: \"各種アサーション機能のテスト\"\n    steps:\n      - instruction: \"「Example Domain」が表示されていることを確認\"\n      - instruction: \"URLに「example.com」が含まれることを確認\"\n      - instruction: \"ページタイトルに「Example」が含まれることを確認\"\n      - instruction: \"「存在しないテキスト」が表示されていないことを確認\"\n```\n\n#### サポートされるアサーション種類\n\n**テキスト検証:**\n- `「テキスト」が表示されていることを確認` - ページ上のテキスト存在確認\n- `「テキスト」が表示されていないことを確認` - テキスト非存在確認\n\n**URL検証:**\n- `URLに「text」が含まれることを確認` - URL部分一致確認\n- `URLが「url」で始まることを確認` - URL開始文字列確認  \n- `URLが「url」で終わることを確認` - URL終了文字列確認\n\n**タイトル検証:**\n- `ページタイトルに「text」が含まれることを確認` - タイトル部分一致確認\n- `ページタイトルが「title」であることを確認` - タイトル完全一致確認\n\n**要素検証:**\n- `「ボタン」が存在することを確認` - 要素存在確認\n- `「ボタン」が表示されていることを確認` - 要素表示確認\n- `「ボタン」が表示されていないことを確認` - 要素非表示確認\n\n**フォーム検証:**\n- `「入力欄」の値が「value」であることを確認` - 入力値確認\n- `「チェックボックス」がチェックされていることを確認` - チェックボックス状態確認\n\nアサーション失敗時は詳細なエラーメッセージとスクリーンショットが自動生成されます。\n\n## サポート対象LLMモデル\n\n### 日本語特化モデル（推奨）\n\n| モデル | サイズ | メモリ使用量 | 特徴 |\n|--------|--------|--------------|------|\n| `rinna/japanese-gpt-neox-3.6b` | 3.6B | ~7GB | **デフォルト**、バランス良好 |\n| `cyberagent/open-calm-3b` | 3B | ~6GB | 日本語特化 |\n| `pfnet/plamo-13b` | 13B | ~26GB | PFN製、日英対応 |\n| `pfnet/plamo-13b-instruct` | 13B | ~26GB | 指示チューニング版 |\n\n### 多言語対応モデル\n\n| モデル | サイズ | メモリ使用量 | 対応言語 |\n|--------|--------|--------------|----------|\n| `Qwen/Qwen2-1.5B-Instruct` | 1.5B | ~3GB | 日英中韓他 |\n| `microsoft/phi-2` | 2.7B | ~5GB | 多言語対応 |\n| `TinyLlama/TinyLlama-1.1B-Chat-v1.0` | 1.1B | ~2GB | 軽量チャット |\n\n## ベンチマーク\n\n### 日本語理解性能（参考値）\n\n| モデル | JGLUE | JSQuAD | JCommonsenseQA | 推論速度* |\n|--------|-------|--------|----------------|-----------|\n| `pfnet/plamo-13b-instruct` | **68.9** | **89.2** | **78.4** | 45 tok/s |\n| `rinna/japanese-gpt-neox-3.6b` | 64.2 | 85.1 | 74.6 | **120 tok/s** |\n| `cyberagent/open-calm-3b` | 62.8 | 83.4 | 72.1 | 135 tok/s |\n| `Qwen/Qwen2-1.5B-Instruct` | 58.4 | 79.8 | 68.9 | **180 tok/s** |\n| `microsoft/phi-2` | 55.7 | 76.3 | 65.2 | 165 tok/s |\n\n*RTX 4090での測定値（参考）\n\n### リソース効率\n\n| モデル | VRAM使用量 | 起動時間 | コスト効率 |  \n|--------|------------|----------|------------|\n| `Qwen/Qwen2-1.5B-Instruct` | 3GB | 15s | ⭐⭐⭐⭐⭐ |\n| `rinna/japanese-gpt-neox-3.6b` | 7GB | 30s | ⭐⭐⭐⭐ |\n| `cyberagent/open-calm-3b` | 6GB | 25s | ⭐⭐⭐⭐ |\n| `pfnet/plamo-13b-instruct` | 26GB | 60s | ⭐⭐⭐ |\n\n### 推奨用途別\n\n- **日本語特化**: `rinna/japanese-gpt-neox-3.6b` （デフォルト） 🇯🇵\n- **中国語+日本語**: `Qwen/Qwen2-1.5B-Instruct` 🌏\n- **軽量・高速**: `TinyLlama/TinyLlama-1.1B-Chat-v1.0` ⚡\n- **高精度重視**: `pfnet/plamo-13b-instruct` 🎯\n- **多言語対応**: `Qwen/Qwen2-7B` 🌍\n\n### 各モデルの利用方法\n\nデフォルト以外のモデルを使用する場合は、設定ファイルで指定します：\n\n```bash\n# 中国語対応モデルを使用\nkotoba --config configs/qwen_config.yaml --test-file test.yaml\n\n# 軽量モデルを使用\nkotoba --config configs/tiny_model.yaml --test-file test.yaml\n```\n\nまたは環境変数で指定：\n\n```bash\nexport MODEL_NAME=\"Qwen/Qwen2-1.5B-Instruct\"\nkotoba --test-file test.yaml\n```\n\n## 設定ファイル\n\n### configs/default.yaml\n```yaml\nllm:\n  model_name: \"rinna/japanese-gpt-neox-3.6b\"\n  device: \"auto\"\n  temperature: 0.7\n\nplaywright:\n  browser: \"chromium\"\n  headless: true\n  timeout: 30000\n\ntest:\n  screenshot_on_failure: true\n  retry_count: 3\n```\n\n## MockLLMモード\n\nLLMモデルをダウンロードせずに動作確認できるモードを搭載。正規表現ベースで基本的な日本語指示を解析します。\n\n```bash\n# MockLLMモードで実行\nexport USE_MOCK_LLM=true\nkotoba --test-file tests/mock_test.yaml\n```\n\n対応指示例：\n- 「ボタンをクリックする」\n- 「テキストボックスに『Hello』と入力する」\n- 「https://example.com に移動する」\n- 「3秒待つ」\n- 「スクリーンショットを撮る」\n\n## キャッシュ機能\n\n### 自動キャッシュ\n- HuggingFaceモデル: `~/.cache/huggingface`\n- 初回ダウンロード後は永続保存\n- コンテナ再ビルド時も再利用\n\n### キャッシュ管理\n```bash\n# キャッシュ済みモデル確認\nmake list-models\n\n# キャッシュクリア（必要時のみ）\nmake clean-cache\n```\n\n### ディスク容量目安\n- 軽量モデル（1-2B）: 2-4GB\n- 中型モデル（3-4B）: 6-8GB  \n- 大型モデル（13B）: 25-30GB\n\n## 開発環境\n\n### コマンド一覧\n\n#### ローカル実行コマンド\n```bash\n# インストール\nmake install-local  # pip install + playwright install\n\n# 実行\nkotoba --help       # ヘルプ表示\nmake dev-local      # 開発モード実行\nmake run-local ARGS=\"--config configs/custom.yaml\"\n\n# テスト\npytest tests/       # テスト実行\nruff check src/     # リント実行\n```\n\n#### Docker実行コマンド\n```bash\n# 環境管理\nmake build          # Docker イメージビルド\nmake up             # コンテナ起動\nmake down           # コンテナ停止\nmake shell          # コンテナシェル\n\n# 開発・テスト\nmake dev            # 開発モード実行\nmake test           # テスト実行\nmake lint           # リント実行\nmake format         # コードフォーマット\n\n# モデル管理\nmake download-model MODEL=\u003cmodel_name\u003e\nmake list-models\n\n# クリーンアップ\nmake clean          # 一時ファイル削除\nmake clean-cache    # 全キャッシュ削除\n```\n\n### ディレクトリ構造\n```\nkotoba/\n├── src/kotoba/           # メインコード\n│   ├── llm.py            # LLM管理\n│   ├── browser.py        # Playwright管理\n│   └── config.py         # 設定管理\n├── configs/              # 設定ファイル\n│   ├── default.yaml      # デフォルト設定\n│   ├── dev.yaml          # 開発環境設定\n│   └── models.yaml       # モデル一覧\n├── tests/                # テストコード\n├── outputs/              # 実行結果出力\n└── docker-compose.yml    # Docker設定\n```\n\n## システム要件\n\n### ローカル実行（推奨）\n- Python 3.10+ \n- 4GB RAM (軽量モデル使用時)\n- 10GB ディスク容量\n\n### Docker実行\n- Docker \u0026 Docker Compose\n- 4GB RAM (軽量モデル使用時)\n- 10GB ディスク容量\n\n### 推奨要件（両方共通）\n- 16GB RAM \n- GPU対応（CUDA/MPS）\n- 50GB ディスク容量（複数モデル使用時）\n\n## トラブルシューティング\n\n### Python 3.13でのpydanticビルドエラー\n\nPython 3.13ではpydantic 2.5.0のビルドが失敗します。以下の対応を推奨：\n- Python 3.10-3.12を使用\n- Docker環境で実行\n- MockLLMモードで実行\n\n### Dockerビルドが遅い\n\n初回ビルド時はLLMモデルのダウンロードに時間がかかります。以下を推奨：\n- 事前に`make download-model`を実行\n- 軽量版の`make test-light`を使用\n- MockLLMモードで開発\n\n## ライセンス\n\nMIT License\n\n## 貢献\n\nプルリクエストやIssueは歓迎します。\n\n---\n\n**kotoba** - 日本語自然言語でWebテストを実行するツール","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xkaz%2Fkotoba","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0xkaz%2Fkotoba","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xkaz%2Fkotoba/lists"}