Skip to content

Commit b7c01ec

Browse files
vipbhardwajvipbhardwaj
committed
refactor: CLAUDE import AGENTS, single-file storing content
1 parent f2ef55b commit b7c01ec

19 files changed

Lines changed: 1131 additions & 2611 deletions

File tree

‎AGENTS.md‎

Lines changed: 145 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -1,91 +1,172 @@
1-
# AGENTS.md — Couchbase Lite System Test Harness
1+
# Couchbase Lite System Test Harness (TDK)
22

3-
## Project Purpose and Scope
3+
System-level test harness for Couchbase Lite releases across all supported platforms. Drives per-platform test servers from a Python framework against Sync Gateway (SGW) and Couchbase Server (CBS).
44

5-
This repository validates Couchbase Lite behavior across platform test servers against Sync Gateway and Couchbase Server.
6-
It includes:
7-
- Python test framework in `client/` (`cbltest`)
8-
- System test suites in `tests/dev_e2e/` and `tests/QE/`
9-
- Environment provisioning in `environment/` (AWS primary, Docker secondary)
10-
- Platform server implementations in `servers/`
11-
- CI orchestration in `jenkins/` and `.github/workflows/`
5+
## Architecture
126

13-
Use existing workflow commands and fixtures; do not invent alternate stacks.
7+
```
8+
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────────────┐
9+
│ Environment │────▶│ Client (TDK) │────▶│ Test Servers │
10+
│ CBS + SGW + ES │ │ Python framework │ │ C │ .NET │ iOS │ JVM │ JS│
11+
│ (AWS / Docker) │ │ `cbltest` package│ │ (per-platform binaries) │
12+
└──────────────────┘ └────────┬─────────┘ └──────────────────────────┘
13+
│
14+
┌───────▼────────┐
15+
│ Tests │
16+
│ dev_e2e / QE │
17+
└────────────────┘
18+
```
19+
20+
## Directory Map
21+
22+
| Path | Contents | Sub-doc |
23+
|------------------|-------------------------------------------------------------------------------------------|---------------------------------------------|
24+
| `client/` | `cbltest` Python framework, pytest plugins, request/response API | [client/AGENTS.md](client/AGENTS.md) |
25+
| `tests/` | `dev_e2e/` (12 test modules + 1 data helper) and `QE/` (20 tests + 12 edge-server tests) | [tests/AGENTS.md](tests/AGENTS.md) |
26+
| `servers/` | Per-platform test servers: `c/`, `dotnet/`, `ios/`, `jak/`, `javascript/` | [servers/AGENTS.md](servers/AGENTS.md) |
27+
| `environment/` | `aws/` (Terraform + orchestrator), `docker/`, `LogSlurp/`, `otel-collector/` | [environment/AGENTS.md](environment/AGENTS.md) |
28+
| `jenkins/` | CI/CD pipelines under `pipelines/{dev_e2e,QE}/{platform}/` | [jenkins/AGENTS.md](jenkins/AGENTS.md) |
29+
| `spec/` | OpenAPI spec (`api/api.yaml`), test specs, dataset docs | [spec/AGENTS.md](spec/AGENTS.md) |
30+
| `dataset/` | Test datasets: cblite2 databases, SGW configs, blobs | — |
31+
32+
## Prerequisites
33+
34+
- Python 3.10+
35+
- `uv` ([docs](https://docs.astral.sh/uv/))
36+
- Git LFS (install **before** cloning — the repo carries binary datasets via LFS)
37+
38+
## Setup
39+
40+
```bash
41+
bash scripts/setup-hooks.sh # installs uv (if missing), syncs deps, installs git hooks
42+
```
1443

1544
## Core Commands
1645

1746
Run from repo root unless noted.
1847

1948
```bash
49+
# Install deps
2050
uv sync
21-
bash scripts/setup-hooks.sh
51+
52+
# Lint & format
2253
uv run ruff check .
2354
uv run ruff format .
55+
56+
# Type check
2457
uv run --group lint ty check
58+
59+
# Pre-commit suite
2560
uv run pre-commit run --all-files
61+
62+
# Framework tests (used in CI)
2663
uv run -- pytest --config client/tests/empty_config.json client/tests
27-
cd tests/dev_e2e && uv run pytest -x -v --config config.json
28-
cd tests/QE && uv run pytest -x -v --config config.json
64+
65+
# Smoke tests
2966
cd client/smoke_tests && uv run pytest -x -v --config config_in.json
67+
68+
# dev_e2e / QE suites
69+
cd tests/dev_e2e && uv run pytest -x -v --config config.json
70+
cd tests/QE && uv run pytest -x -v --config config.json
71+
72+
# AWS environment (requires `aws sso login`)
3073
cd environment/aws && uv run python start_backend.py --topology topology_setup/topology.json
31-
cd environment/aws && uv run python stop_backend.py --topology topology_setup/topology.json
74+
cd environment/aws && uv run python stop_backend.py --topology topology_setup/topology.json
75+
76+
# Local Docker environment (CBS + SGW + LogSlurp)
77+
cd environment/docker && python start_environment.py
3278
```
3379

34-
## Repo Layout
35-
36-
- `client/`: `cbltest` package, pytest plugins, smoke tests
37-
- `tests/`: `dev_e2e` and `QE` suites plus fixtures/logs
38-
- `servers/`: C, .NET, iOS, JVM, JavaScript test server implementations
39-
- `environment/aws/`: Terraform + Python orchestrator for CBS/SGW/ES/LB/LogSlurp/test servers
40-
- `environment/docker/`: local Docker environment
41-
- `jenkins/pipelines/`: dev_e2e/QE platform setup and execution pipelines
42-
- `spec/`: OpenAPI and test specifications
43-
- `dataset/`: datasets used by tests
44-
45-
## Development Patterns and Constraints
46-
47-
- Python baseline is 3.10+ (`X | Y`, not `Union` / `Optional`).
48-
- Async patterns are standard for test and framework I/O (`aiohttp`, `pytest-asyncio`).
49-
- `config.json` in test directories is generated; do not hand-edit for CI workflows.
50-
- Maintain compatibility for request/response API versions v1 and v2 in `client/src/cbltest/v1` and `v2`.
51-
- Reuse existing marker and fixture patterns:
52-
- topology markers (`min_test_servers`, `min_sync_gateways`, etc.)
53-
- `cblpytest` fixture
54-
- `dataset_path` fixture
55-
- Prefer shared orchestration/utilities over duplication:
56-
- `environment/aws/common/*`
57-
- `jenkins/pipelines/shared/*`
58-
- Keep platform behavior behind existing bridge/registration abstractions in `environment/aws/topology_setup/test_server_platforms/`.
59-
60-
## Validation and Evidence Before Completion
61-
62-
Before finishing any change, provide evidence from applicable validators:
63-
64-
1. Lint/format: `uv run ruff check .` and `uv run ruff format .` (or check mode as required by task)
65-
2. Type checks: `uv run --group lint ty check` (the `lint` group contains `ty`; use it for all paths including orchestrator)
66-
3. Hooks when relevant: `uv run pre-commit run --all-files`
67-
4. Tests scoped to changed area:
68-
- `client/`: `uv run -- pytest --config client/tests/empty_config.json client/tests` and/or `client/smoke_tests`
69-
- `tests/dev_e2e` or `tests/QE`: run targeted pytest command with `--config`
70-
- `environment/` changes: run the touched script CLI `--help` and dry-run-safe checks where possible
80+
## Python Workspace
81+
82+
`uv` workspace with two members:
83+
- Root `pyproject.toml` — top-level project, depends on `cbltest`
84+
- `client/pyproject.toml` — the `cbltest` package (hatchling build)
85+
86+
Dependency groups in root:
87+
- `lint` — `ty`, `ruff`, type stubs (use `uv run --group lint …`)
88+
89+
AWS orchestrator scripts run from the root workspace — there is **no** separate `orchestrator` group.
90+
91+
## Coding Standards
92+
93+
- **Python 3.10+** — use `X | Y`, never `Union[X, Y]` / `Optional[X]`. Enforced by `pyupgrade --py310-plus` in pre-commit.
94+
- **Async everywhere** — test and framework I/O use `aiohttp` + `pytest-asyncio`.
95+
- **Formatting / linting** — `ruff` (with `I` import sorting) and `ruff-format`.
96+
- **Type checking** — `ty` (config in `[tool.ty.environment]`).
97+
- **Request/response versioning** — API v1 and v2 live in `client/src/cbltest/v1/` and `v2/`. Register via `@register_request(TestServerRequestType.X, version=N)` and `@register_body(...)`. `version.py::available_api_version()` is the source of truth.
98+
- **Reuse shared utilities** — `environment/aws/common/*`, `jenkins/pipelines/shared/*`. Don't reinvent file transfer, Docker ops, or Terraform parsing.
99+
100+
## Test Conventions
101+
102+
- Test files: `test_<feature>.py`; functions: `async def test_<…>(...)`.
103+
- Use the `cblpytest` fixture (auto-injected by `cbltest.plugins.cblpytest_fixture`).
104+
- Use the `dataset_path` fixture (defined per-suite in `conftest.py`).
105+
- Topology markers: `@pytest.mark.min_test_servers(N)`, `@pytest.mark.min_sync_gateways(N)`, etc.
106+
- Behavior markers: `@pytest.mark.sgw`, `.cbl`, `.upg_sgw`.
107+
- QE tests auto-clean via the `cleanup_after_test` fixture.
108+
109+
## Config Files (Generated — Do Not Hand-Edit)
110+
111+
- Test config: `tests/{dev_e2e,QE}/config.json` (schema: `https://packages.couchbase.com/couchbase-lite/testserver.schema.json`)
112+
- Topology: `environment/aws/topology_setup/*.json` (schema: `topology_schema.json`)
113+
114+
## Git Hooks
115+
116+
`.pre-commit-config.yaml` enforces on every commit:
117+
- **Syntax / style**: ruff (lint + import sort), ruff-format, pyupgrade, ty
118+
- **Merge safety**: check-merge-conflict, check-executables-have-shebangs, check-shebang-scripts-are-executable
119+
- **Commit format**: Conventional Commits via `scripts/hooks/check-commit-msg.sh` (`<type>[scope]: <description>`)
120+
121+
`scripts/setup-hooks.sh` additionally installs `detect-secrets` and generates `.secrets.baseline` for **manual** scans. It is not wired into pre-commit — run `detect-secrets scan --baseline .secrets.baseline` manually before pushing changes that touch credentials, hostnames, or generated configs.
122+
123+
## Recurring Patterns (Know Before Editing)
124+
125+
1. **Jenkins per-platform `setup_test.py`** — every file under `jenkins/pipelines/{dev_e2e,QE}/{platform}/` is a thin click wrapper calling `setup_test(...)` from `jenkins/pipelines/shared/`. Only `platform_name`, `topology_file`, and `config_file` differ.
126+
2. **`conftest.py` `dataset_path` fixtures** — three near-identical copies in `tests/dev_e2e/`, `tests/QE/`, `client/smoke_tests/` differing only in relative depth to `dataset/sg/`.
127+
3. **Server build scripts** — every platform under `servers/` follows: `download_cbl.sh` → `build_*.sh` → package.
128+
4. **AWS setup scripts** — every `environment/aws/*_setup/setup_*.py` follows: SSH via `paramiko` → SFTP upload → `remote_exec` → start service (Docker / systemd).
129+
130+
## CI/CD
131+
132+
- `.github/workflows/python_verify.yml` — runs `ty check`, `ruff format --check`, `ruff check` on Python changes.
133+
- `.github/workflows/openapi.yml` — Redocly lint + yamllint on `spec/api/` changes; posts PR preview link.
134+
- `jenkins/pipelines/prebuild/` — builds test-server artifacts.
135+
- `jenkins/pipelines/{dev_e2e,QE}/{platform}/` — per-platform CI runs.
136+
137+
## Validation Before Completion
138+
139+
For every code change provide evidence from applicable validators:
140+
141+
1. Lint/format: `uv run ruff check .` and `uv run ruff format .`
142+
2. Types: `uv run --group lint ty check`
143+
3. Hooks: `uv run pre-commit run --all-files`
144+
4. Tests scoped to the changed area:
145+
- `client/` → `client/tests` and/or `client/smoke_tests`
146+
- `tests/dev_e2e` or `tests/QE` → targeted pytest with `--config`
147+
- `environment/` → run the touched script with `--help` and dry-run-safe checks
71148

72149
If full integration tests are not runnable locally, state exactly what was run and what remains.
73150

74-
## Security and Sensitive Paths
151+
## Security & Sensitive Paths
75152

76-
- Never commit secrets, keys, tokens, certificates, or Terraform state.
77-
- Treat these as sensitive:
78-
- `.secrets.baseline`
79-
- `environment/aws/temp.pem`
80-
- `environment/aws/terraform.tfstate*` (if present locally)
81-
- generated configs containing hostnames/credentials
82-
- Use `detect-secrets`/pre-commit findings as blockers, not warnings.
153+
- **Never commit**: secrets, keys, tokens, certificates, or Terraform state.
154+
- Treat as sensitive: `.secrets.baseline`, `environment/aws/temp.pem`, `environment/aws/terraform.tfstate*`, generated configs containing hostnames/credentials.
83155
- Avoid logging credentials or signed URLs in test output and fixtures.
84156

157+
## Markdown Discipline
158+
159+
Markdown files in this repo serve a narrow purpose. **Do not** create new markdown files to document code changes (e.g. `ENHANCEMENT_SUMMARY.md`, `IMPLEMENTATION_GUIDE.md`). Code changes belong in code; PR descriptions explain motivation.
160+
161+
Markdown files that belong in the repo:
162+
- `AGENTS.md` — single source of truth per directory (this file and its peers); `CLAUDE.md` is a one-line import of the same content for Claude Code's auto-loading.
163+
- `README.md` — getting-started guides.
164+
- `spec/**/*.md` — API supplements, test specifications, dataset docs.
165+
85166
## Supporting Agent Context
86167

87-
- `docs/architecture.agents.md` — runtime boundaries and end-to-end flow
88-
- `docs/agent-context/repo-inventory.md` — tools, directories, configs, unknowns
89-
- `docs/agent-context/build-test-matrix.md` — copy-pasteable validation commands by component
90-
- `docs/agent-context/domain-glossary.md` — system terms and acronyms
91-
- `docs/agent-context/troubleshooting.md` — common setup/CI/test failures
168+
- [docs/architecture.agents.md](docs/architecture.agents.md) — runtime boundaries and end-to-end flow
169+
- [docs/agent-context/repo-inventory.md](docs/agent-context/repo-inventory.md) — tools, directories, configs
170+
- [docs/agent-context/build-test-matrix.md](docs/agent-context/build-test-matrix.md) — copy-pasteable validation commands
171+
- [docs/agent-context/domain-glossary.md](docs/agent-context/domain-glossary.md) — system terms and acronyms
172+
- [docs/agent-context/troubleshooting.md](docs/agent-context/troubleshooting.md) — common setup/CI/test failures

0 commit comments

Comments
 (0)