docs: sync V2 status and process docs for issue #131

2026-02-16 11:58:49 +09:00
parent 31b4d0bf1e
commit cc1489fd7c
7 changed files with 347 additions and 1081 deletions
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -1,213 +1,56 @@
 # Testing Guidelines

-## Test Structure
+## Current Test Baseline (2026-02-16)

-**54 tests** across four files. `asyncio_mode = "auto"` in pyproject.toml — async tests need no special decorator.
-
-The `settings` fixture in `conftest.py` provides safe defaults with test credentials and in-memory DB.
-
-### Test Files
-
-#### `tests/test_risk.py` (11 tests)
- Circuit breaker boundaries
- Fat-finger edge cases
- P&L calculation edge cases
- Order validation logic
-
-**Example:**
-```python
-def test_circuit_breaker_exact_threshold(risk_manager):
-    """Circuit breaker should trip at exactly -3.0%."""
-    with pytest.raises(CircuitBreakerTripped):
-        risk_manager.validate_order(
-            current_pnl_pct=-3.0,
-            order_amount=1000,
-            total_cash=10000
-        )
-```
-
-#### `tests/test_broker.py` (6 tests)
- OAuth token lifecycle
- Rate limiting enforcement
- Hash key generation
- Network error handling
- SSL context configuration
-
-**Example:**
-```python
-async def test_rate_limiter(broker):
-    """Rate limiter should delay requests to stay under 10 RPS."""
-    start = time.monotonic()
-    for _ in range(15):  # 15 requests
-        await broker._rate_limiter.acquire()
-    elapsed = time.monotonic() - start
-    assert elapsed >= 1.0  # Should take at least 1 second
-```
-
-#### `tests/test_brain.py` (18 tests)
- Valid JSON parsing
- Markdown-wrapped JSON handling
- Malformed JSON fallback
- Missing fields handling
- Invalid action validation
- Confidence threshold enforcement
- Empty response handling
- Prompt construction for different markets
-
-**Example:**
-```python
-async def test_confidence_below_threshold_forces_hold(brain):
-    """Decisions below confidence threshold should force HOLD."""
-    decision = brain.parse_response('{"action":"BUY","confidence":70,"rationale":"test"}')
-    assert decision.action == "HOLD"
-    assert decision.confidence == 70
-```
-
-#### `tests/test_market_schedule.py` (19 tests)
- Market open/close logic
- Timezone handling (UTC, Asia/Seoul, America/New_York, etc.)
- DST (Daylight Saving Time) transitions
- Weekend handling
- Lunch break logic
- Multiple market filtering
- Next market open calculation
-
-**Example:**
-```python
-def test_is_market_open_during_trading_hours():
-    """Market should be open during regular trading hours."""
-    # KRX: 9:00-15:30 KST, no lunch break
-    market = MARKETS["KR"]
-    trading_time = datetime(2026, 2, 3, 10, 0, tzinfo=ZoneInfo("Asia/Seoul"))  # Monday 10:00
-    assert is_market_open(market, trading_time) is True
-```
-
-## Coverage Requirements
-
-**Minimum coverage: 80%**
-
-Check coverage:
-```bash
-pytest -v --cov=src --cov-report=term-missing
-```
-
-Expected output:
-```
-Name                          Stmts   Miss  Cover   Missing
-----------------------------------------------------------
-src/brain/gemini_client.py       85      5    94%   165-169
-src/broker/kis_api.py           120     12    90%   ...
-src/core/risk_manager.py         35      2    94%   ...
-src/db.py                        25      1    96%   ...
-src/main.py                     150     80    47%   (excluded from CI)
-src/markets/schedule.py          95      3    97%   ...
-----------------------------------------------------------
-TOTAL                           510     103   80%
-```
-
-**Note:** `main.py` has lower coverage as it contains the main loop which is tested via integration/manual testing.
-
-## Test Configuration
-
-### `pyproject.toml`
-```toml
-[tool.pytest.ini_options]
-asyncio_mode = "auto"
-testpaths = ["tests"]
-python_files = ["test_*.py"]
-```
-
-### `tests/conftest.py`
-```python
-@pytest.fixture
-def settings() -> Settings:
-    """Provide test settings with safe defaults."""
-    return Settings(
-        KIS_APP_KEY="test_key",
-        KIS_APP_SECRET="test_secret",
-        KIS_ACCOUNT_NO="12345678-01",
-        GEMINI_API_KEY="test_gemini_key",
-        MODE="paper",
-        DB_PATH=":memory:",  # In-memory SQLite
-        CONFIDENCE_THRESHOLD=80,
-        ENABLED_MARKETS="KR",
-    )
-```
-
-## Writing New Tests
-
-### Naming Convention
- Test files: `test_<module>.py`
- Test functions: `test_<feature>_<scenario>()`
- Use descriptive names that explain what is being tested
-
-### Good Test Example
-```python
-async def test_send_order_with_market_price(broker, settings):
-    """Market orders should use price=0 and ORD_DVSN='01'."""
-    # Arrange
-    stock_code = "005930"
-    order_type = "BUY"
-    quantity = 10
-
-    # Act
-    with patch.object(broker._session, 'post') as mock_post:
-        mock_post.return_value.__aenter__.return_value.status = 200
-        mock_post.return_value.__aenter__.return_value.json = AsyncMock(
-            return_value={"rt_cd": "0", "msg1": "OK"}
-        )
-
-        await broker.send_order(stock_code, order_type, quantity, price=0)
-
-    # Assert
-    call_args = mock_post.call_args
-    body = call_args.kwargs['json']
-    assert body['ORD_DVSN'] == '01'  # Market order
-    assert body['ORD_UNPR'] == '0'   # Price 0
-```
-
-### Test Checklist
- [ ] Test passes in isolation (`pytest tests/test_foo.py::test_bar -v`)
- [ ] Test has clear docstring explaining what it tests
- [ ] Arrange-Act-Assert structure
- [ ] Uses appropriate fixtures from conftest.py
- [ ] Mocks external dependencies (API calls, network)
- [ ] Tests edge cases and error conditions
- [ ] Doesn't rely on test execution order
-
-## Running Tests
+수집 기준:

 ```bash
-# All tests
-pytest -v
-
-# Specific file
-pytest tests/test_risk.py -v
-
-# Specific test
-pytest tests/test_brain.py::test_parse_valid_json -v
-
-# With coverage
-pytest -v --cov=src --cov-report=term-missing
-
-# Stop on first failure
-pytest -x
-
-# Verbose output with print statements
-pytest -v -s
+pytest --collect-only -q
+# 538 tests collected
 ```

-## CI/CD Integration
+V2 핵심 영역 테스트가 포함되어 있습니다.

-Tests run automatically on:
- Every commit to feature branches
- Every PR to main
- Scheduled daily runs
+- `tests/test_strategy_models.py`
+- `tests/test_pre_market_planner.py`
+- `tests/test_scenario_engine.py`
+- `tests/test_playbook_store.py`
+- `tests/test_context_scheduler.py`
+- `tests/test_daily_review.py`
+- `tests/test_scorecard.py`
+- `tests/test_dashboard.py`
+- `tests/test_main.py`

-**Blocking conditions:**
- Test failures → PR blocked
- Coverage < 80% → PR blocked (warning only for main.py)
+## Required Checks

-**Non-blocking:**
- `mypy --strict` errors (type hints encouraged but not enforced)
- `ruff check` warnings (must be acknowledged)
+```bash
+pytest -v --cov=src
+ruff check src/ tests/
+mypy src/ --strict
+```
+
+## FastAPI Note
+
+대시보드 테스트(`tests/test_dashboard.py`)는 `fastapi`가 환경에 없으면 skip될 수 있습니다.
+의도된 동작이며 CI/개발환경에서 의존성 설치 여부를 확인하세요.
+
+## Targeted Smoke Commands
+
+```bash
+# dashboard integration
+pytest -q tests/test_main.py -k "dashboard"
+
+# planner/scenario/review paths
+pytest -q tests/test_pre_market_planner.py tests/test_scenario_engine.py tests/test_daily_review.py
+
+# context rollup/scheduler
+pytest -q tests/test_context.py tests/test_context_scheduler.py
+```
+
+## Review Checklist (테스트 관점)
+
+- 플랜 항목별 테스트 존재 여부 확인
+- 시장 스코프 키(`*_KR`, `*_US`) 검증 확인
+- EOD 흐름(`aggregate_daily_from_trades`, `scorecard_{market}` 저장) 검증
+- decision outcome 연결(`decision_id`) 검증
+- 대시보드 API market filter 검증