# CLAUDE.md

Guidance for Claude Code (claude.ai/code) when working in this repository.

> This repo is an automated test suite for cloud APIs on **Verda KKS region** and **LY Flava cloud**, built on the OpenStack Tempest-style framework (pytest + service clients + schema validation).

---

## Golden Rules (Must Follow)

1. **Never pass `project_name` into service client methods.**
   Client methods must use `self.project_name` (from credentials/auth context).
   ✅ `url = .../{self.project_name}/...`
   ❌ `create_x(project_name=...)`

2. **Service naming consistency is critical.**
   The following identifiers **MUST match** (same string):
   - `cfg.OptGroup(name="<config_name>")` in `configs/config.py`
   - directory `lib/services/<config_name>/`
   - key `"<config_name>"` in `lib/services/clients.py: tempest_modules()`
   - credential attribute prefix in `lib/auth.py` (e.g., `<config_name>_access_token`, `<config_name>_token`)

3. **No secrets in code or commits.**
   - Never hardcode passwords/tokens/base URLs in tests or clients.
   - Do not commit `.env`, `accounts.yaml`, logs, or Allure outputs.
   - Avoid logging headers that contain tokens.

4. **Cloud-specific logic must be gated.**
   - Only initialize Flava-only clients when `CONF.common.target_cloud == "flava"`.
   - Use `@pytest.mark.env_only("flava")` / `@pytest.mark.env_only("verda")` to guard tests.

---

## Glossary (Avoid Confusion)

- **config_name**: `cfg.OptGroup(name="...")` — primary identifier across the codebase (Rule #2).
- **catalog_type**: Service catalog name used to resolve endpoints (may differ from config_name).
- **auth header pattern**:
  - Bearer token: `Authorization: Bearer <token>`
  - X-Auth-Token: `X-Auth-Token: <token>`
- **Athenz service name**: token generation name used in `scripts/account_generator.sh` (can differ from config_name).

---

## Quick Start

### Installation (Use .venv)

[NOTE] Use .venv/bin/python for all pip/pytest commands. Do not rely on `source .venv/bin/activate`.

Commands:
1) Create venv (first time)
   python3 -m venv .venv 2>/dev/null || python -m venv .venv

2) Upgrade packaging tools
   .venv/bin/python -m pip install -U pip setuptools wheel

3) Install deps
   .venv/bin/python -m pip install -r requirements.txt

---

### Environment Variables

**Common**
- `TEST_ENV` (required): selects config file `configs/${TEST_ENV}.conf`

**Flava**
- `ENVIRONMENT` (optional): defaults to `stage` (valid: `stage`, `dev`, `prod`)

**Examples**
- Flava: `TEST_ENV=flava_stage_dev_kks`

> `.env` files are auto-loaded in `tests/conftest.py` (dotenv).

---

## Configuration

### Config Files
- Location: `configs/`
- Naming: `${TEST_ENV}.conf`
- Loaded during pytest startup (`pytest_configure` hook).

If the config file does not exist, pytest will fail early with `FileNotFoundError`.

### Test Accounts

**Verda (pre-provisioned)**
- Update `configs/accounts.yaml` manually (username/project/password).
- Supports custom role `qa_admin` for elevated operations.

**Flava (generated)**
- Run: bash scripts/account_generator.sh
- Generates Athenz access tokens and updates `accounts.yaml`.

> Tip: Prefer pre-provisioned credentials for Verda to avoid unexpected behavior with dynamic generation.

---

## Markers

Markers are defined in `pytest.ini` (examples):
- `smoke`, `positive`, `negative`, `multinode`, `authorization`
- `tc_repeat(count=n)`: repeats test case n times (collection hook)
- `env_only("flava"|"verda"|...)`: skips tests when env does not match
- `last`, `second_to_last`: ordering control

Marker filtering notes:
- `-m smoke` / `-m positive` works normally.
- `env_only(...)` is enforced by a pytest hook (skip at runtime).
  You can run `-m env_only` to select tests that have the marker, but argument matching is still handled by the hook (tests may still be skipped).

---

## Repository Structure (High-Level)

tests/
  api/                 API-level tests
  scenario/            End-to-end tests
  conftest.py          pytest hooks + env gating + repeats + ordering + reporting
  clients.py           Manager orchestrator (injects service clients)

lib/
  services/            Service client implementations (Tempest-style)
  api_schema/          JSON schemas for response validation
  auth.py              Auth providers & header decoration
  common/              shared utilities (credentials, matchers, utils)

configs/
  *.conf               env-specific configuration
  accounts.yaml        credentials/tokens (DO NOT COMMIT)
  config.py            CONF object and option groups

scripts/
  account_generator.sh  Flava token generation
  release_tempest_locks.sh Manual tempest lock release (if needed)
  cleanup                  Quick alias for release_tempest_locks.sh

.claude/
  skills/
    flava-api-test/      Flava API test automation (add, sync, update)
    skill-creator/       Skill for creating new Claude Code skills

---

## Client Architecture (How tests access APIs)

Tests use Manager instances like:
- self.os_primary
- self.os_admin
- self.os_alt

Access pattern (example):
- server = self.os_primary.servers_client.create_server(...)
- network = self.os_primary.networks_client.create_network(...)
- token = self.os_primary.token_v3_client.get_token(...)

Cloud-specific clients are conditionally initialized based on:
- CONF.common.target_cloud (e.g., "verda" or "flava")

---

## Testing Patterns (Preferred)

Pre-test cleanup:
- pytest automatically cleans up hanging tempest processes and lock files before starting
- No manual intervention needed for most tempest lock conflicts

Allure steps:
- Use allure.step(...) to structure multi-step operations.

Cleanup:
- Prefer helper methods that auto-register cleanup.
- Use test_utils.call_and_ignore_notfound_exc for delete cleanups when appropriate.

Test Markers:
- Use @pytest.mark.positive for valid operations
- Use @pytest.mark.negative for invalid inputs/operations
- Use @pytest.mark.env_only("flava") to gate cloud-specific tests

---

## Troubleshooting (Common)

Config not found:
- Verify TEST_ENV is set
- Confirm configs/${TEST_ENV}.conf exists

Identity v3 enabled but missing endpoint:
- Ensure identity.uri_v3 is configured in the .conf

Test skipped due to env_only:
- env_only("flava") requires "flava" to match your TEST_ENV (hook logic)

Client missing:
- Check CONF.common.target_cloud and Manager _set_*_clients() gating
- Ensure service is registered in tempest_modules() and directory names match

Tempest lock conflicts:
- **Automatic cleanup**: pytest automatically checks for and cleans up hanging tempest processes and lock files before starting tests
- **Manual cleanup**: if needed, run `./scripts/cleanup` or `./scripts/release_tempest_locks.sh` to manually release locks
- These tools kill any hanging pytest processes and remove the tempest_lock directory