# Live Contract Test Guide

`tests/contract` is the repository-owned home for live, end-to-end API compatibility tests against the Salesforce-shaped surface implemented by this backend.

## Scope

- Applicable scope: `tests/contract/**`
- Compatibility target: Salesforce API `v63.0`
- Test style: live AAA with `testify`
- Runtime targets:
  - Salesforce sandbox, configured from [sandbox.yaml](sandbox.yaml)
  - NexusCRM local backend

## Service Boundaries

Contract tests are organized by top-level API family that the backend actually exposes:

- `rest_api`
- `ui_api`
- `bulk_api_v2`
- `metadata_api`
- `tooling_api`
- `streaming_api`
- `connect_api`
- `analytics_api`

These stay inside `rest_api`, not their own top-level services:

- `composite`
- `query`
- `search`
- `process`
- `sobjects`
- `folders`
- `actions`

## Source Of Truth

Use official Salesforce documentation as the source of truth. Start from the shared index and then the service-specific guide declared in each service directory.

- Shared index: [Integration & APIs Developer Center](https://developer.salesforce.com/devcenter/integration-apis)

Notes:

- Prefer HTML docs only.
- Do not use PDF docs as the primary source.
- Treat [salesforce.postman_collection.json](salesforce.postman_collection.json) as a discovery aid only, not as the authoritative contract source. Its request templates and parameter labels are often less detailed than the official API docs.
- When Postman and official docs disagree, or when Postman omits parameter typing, requiredness, enums, body fields, or response semantics, the official Salesforce HTML docs win.
- Many suites intentionally use a doc-set version such as `254.0` together with runtime target `v63.0`. Do not collapse those into one number unless the service guide explicitly requires it.

## Documentation Crawl Workflow

Before adding or updating endpoint coverage, crawl the matching Salesforce API docs and update `catalog.yaml` as an index file only.

Required workflow:

1. Use backend-mounted routes and service boundaries to determine which service owns the endpoint.
2. Use Postman only to discover candidate paths, request names, and API families.
3. Find the corresponding official Salesforce HTML page for each `method + path`.
4. Prefer the endpoint-specific documentation page when it exists; otherwise use the closest official overview or resource page.
5. Record only the endpoint index fields in `catalog.yaml`. Do not store parameter tables, body schemas, response summaries, notes, or prose digests there.
6. If no official page can be confirmed, keep `doc: todo` and resolve that gap later instead of inventing a URL.

## Directory Shape

Each service directory should converge on this layout:

```text
tests/contract/<api_service>/
├── AGENTS.md
├── REPORT.md
├── catalog.yaml
├── suite_test.go
├── client/
├── internal/
│   └── arrange/
└── <category>/
    └── <method>_<path_slug>_test.go
```

If transitional directories such as `consumers/`, `providers/`, `pacts/`, `generated_client/`, or `docs_catalog.yaml` are still present, they are cleanup debt, not the target design.

## Compatibility Status Legend

Use the same compatibility legend in service `REPORT.md` files and in any synced tracking issue.

- `🚫`: explicitly not implemented
- `⭕`: no test coverage, so it cannot be verified yet
- `🔴`: implemented but incompatible, unusable, or seriously wrong in behavior or schema
- `🟡`: implemented and usable, but with tested behavioral or schema deviations
- `🟢`: fully compatible with the official documented behavior

When syncing a GitHub tracking issue from a service report:

- Write the issue body in English.
- Keep `Context` and `Summary` high-level.
- Keep `Summary` free of status symbols and avoid long paragraphs.
- Prefer short bullets or short paragraphs in issue body prose.
- Put endpoint-by-endpoint evidence, concrete examples, and verification commands in the service `REPORT.md`.
- Use the issue body as a progress board, not as a duplicate of the report narrative.

## Working Rules

1. Tests must be live, end-to-end, and use real HTTP requests.
2. Do not use mocks, fake providers, Pact artifacts, or canned response bodies as the test oracle.
3. Arrange may create and clean up real sandbox or local resources when needed.
4. Every endpoint is identified by `method + path`.
5. Same path with different methods must be split into separate endpoint files.
6. Use table-driven tests to cover documented parameter combinations, missing fields, invalid values, enums, and business constraints.
7. `catalog.yaml` is a strict endpoint index file. Keep it at endpoint granularity, one row per `method + path`.
8. The only allowed top-level keys in `catalog.yaml` are:
   - `api_service`
   - `compatibility_target`
   - `entry_points`
   - `categories`
9. `crawl_entry_points` is not allowed. Use `entry_points` consistently in every service.
10. `notes`, `catalog`, `schema_version`, category-level `docs`, endpoint-level prose fields, and any other extra top-level metadata are not allowed in `catalog.yaml`.
11. Each `entry_points` item must contain only:

    - `label`
    - `url`

12. Each category item must contain only:

    - `category`
    - `endpoints`

13. Each endpoint item must contain only:

    - `name`
    - `method`
    - `path`
    - `doc`
    - `coverage`
    - `test_file`

14. If an endpoint does not yet have a test file, omit `test_file` rather than adding any substitute field.
15. `REPORT.md` is the place for execution findings, caveats, and narrative context. Do not move that prose into `catalog.yaml`.
16. Prefer shared transport/auth helpers and lightweight typed clients, but do not generate endpoint tests from scripts.
17. If a backend route is not actually mounted in [routes.go](../../backend/cmd/server/routes.go), do not pretend it is covered by contract tests.

## Config Rules

1. [sandbox.yaml](sandbox.yaml) is the canonical committed sandbox config artifact.
2. Service-local env vars may continue to exist during migration, but they should resolve to the same `v63.0` compatibility target.
3. Local backend defaults should stay reproducible from this repository. Do not depend on ad hoc host-machine setup when the repo can bootstrap the required state.

## Verification

At minimum:

- `go test ./... -run '^$'` must pass from `tests/contract`
- each touched service must keep a reproducible verification command in its `REPORT.md`
- if a service still carries transitional directories, either remove them or document the reason in the service `REPORT.md`