forked from Yara724/api
s.hajizadeh
0f9f702a00
Track the tester and env template in git so a new tenant can be exercised without a YARA claim; keep filled client env files (secrets, national codes) ignored. Co-authored-by: Cursor <cursoragent@cursor.com>
181 lines
7.3 KiB
Markdown
181 lines
7.3 KiB
Markdown
---
|
||
last_updated: 2026-08-17
|
||
tags: [fanavaran, testing]
|
||
source: fanavaran-module-docs
|
||
---
|
||
|
||
# 10 — Testing
|
||
|
||
## Prerequisites
|
||
|
||
1. `FANAVARAN_CLIENT=parsian` (or target tenant)
|
||
2. Valid tenant credentials in Mongo / seed
|
||
3. `INSURANCE_CORP_ID` matching that tenant’s insurance-corp Caption
|
||
4. Network access to `apimanager.iraneit.com`
|
||
5. Optional: warm lookups via first `GET /lookups/fanavaran/{name}` or auth script
|
||
|
||
## Auth smoke test
|
||
|
||
```bash
|
||
scripts/fanavaran-auth.sh parsian
|
||
source files/fanavaran-auth/parsian/tokens.env
|
||
# then curl a lookup — see docs/external-api-curls.md
|
||
```
|
||
|
||
## Manual Fanavaran flow test (no YARA)
|
||
|
||
Use this when there is **no YARA claim** and you need to prove a tenant (Parsian / Tejaratno / Moallem) against Fanavaran with the **same stage order as the app**.
|
||
|
||
Files in git:
|
||
|
||
| Path | Role |
|
||
|------|------|
|
||
| `scripts/fanavaran-flow-test.sh` | Standalone tester |
|
||
| `scripts/data/fanavaran-flow.env.example` | Template env (section A = you fill, section B = script fills) |
|
||
|
||
Do **not** commit a filled copy (`fanavaran-flow.moallem.env` and similar). It contains national codes, plate data, and secrets. Copy the example on the machine that runs the test.
|
||
|
||
### 1. Copy and fill the env
|
||
|
||
```bash
|
||
cp scripts/data/fanavaran-flow.env.example scripts/data/fanavaran-flow.<client>.env
|
||
```
|
||
|
||
Fill **section A** before the first run:
|
||
|
||
- Tenant: `FANAVARAN_CLIENT`, optional auth overrides (`APP_NAME`, `CORP_ID`, `LOCATION`, …)
|
||
- Lookup ids **from that tenant** (`files/fanavaran-lookups/<client>/`): `CLAIM_EXPERT_ID`, `EXPERTISE_CLAIM_EXPERT_ID`, `CLAIM_FILE_TYPE_ID`, `VEHICLE_KIND_ID`, `DMG_SECTION_ID`
|
||
- `INSURANCE_CORP_ID`: Persian caption **or** numeric Fanavaran Id
|
||
- Case data: guilty national code, driver national code + Jalali birthday, plate/chassis/VIN if you have them
|
||
- `ATTACHMENT_FILE`: absolute path(s) to image(s) **on the host that runs the script** (comma-separated for several files)
|
||
- Leave **section B empty** (`POLICY_ID`, `CLAIM_ID`, …)
|
||
|
||
Lookup ids from Tejaratno/Parsian files are invalid for Moallem (Fanavaran returns `نوع خودرو یافت نشد` and similar). Fetch Moallem lookups first (`GET /lookups/vehicle-kinds` with `FANAVARAN_CLIENT=moallem`, or curl Fanavaran with that tenant’s token).
|
||
|
||
### 2. Network / IP whitelist
|
||
|
||
Fanavaran Login is IP-restricted. From a **whitelisted server**, run with no proxy. From **localhost**, Termius dynamic port forwarding does **not** apply automatically — set:
|
||
|
||
```env
|
||
CURL_PROXY=socks5h://127.0.0.1:<termius-socks-port>
|
||
```
|
||
|
||
Error `کاربر … مجاز به لاگین با آی پی … نمیباشد` means curl is still using your home IP.
|
||
|
||
### 3. Run (same sequence as the app)
|
||
|
||
```text
|
||
auth (cached until Tehran midnight)
|
||
→ policy inquiry → GEN.03 base
|
||
→ driver inquiry + insurance-corp
|
||
→ GEN.12 damage
|
||
→ GEN.07 attachments (one request per file)
|
||
→ GEN.08 expertise
|
||
```
|
||
|
||
From repo root (`bash`, `curl`, `node`, `awk` required):
|
||
|
||
```bash
|
||
chmod +x scripts/fanavaran-flow-test.sh
|
||
|
||
# Full flow (confirms before each POST)
|
||
./scripts/fanavaran-flow-test.sh --env scripts/data/fanavaran-flow.moallem.env
|
||
|
||
# One or more stages
|
||
./scripts/fanavaran-flow-test.sh --env scripts/data/fanavaran-flow.moallem.env --stages base,damage
|
||
./scripts/fanavaran-flow-test.sh --env scripts/data/fanavaran-flow.moallem.env --stages attachments
|
||
./scripts/fanavaran-flow-test.sh --env scripts/data/fanavaran-flow.moallem.env --stages expertise
|
||
|
||
# Build payloads / inquiries only
|
||
./scripts/fanavaran-flow-test.sh --env scripts/data/fanavaran-flow.moallem.env --preview-only
|
||
```
|
||
|
||
Missing section-A fields can be typed when prompted; they are written back into the env file.
|
||
|
||
### 4. Token cache (do not Login every run)
|
||
|
||
`authenticationToken` is stored in `files/fanavaran-auth/<client>/tokens.env` until **Asia/Tehran midnight** (same as Nest). Later runs print `Reusing cached authenticationToken`. Use `--force-login` only when you must mint a new token.
|
||
|
||
Repeated Login causes Fanavaran `لطفا پس از چند لحظه مجدد تلاش فرمایید`.
|
||
|
||
### 5. Resume after a stage succeeds
|
||
|
||
Section B is updated in the **same env file**. Re-run; stages with `CLAIM_ID` / `DMG_CASE_ID` already set are skipped (soft-skip). Payloads and HTTP bodies also land under `files/fanavaran-flow/<client>/<timestamp>/` (gitignored).
|
||
|
||
### 6. Typical failures
|
||
|
||
| Message | What to do |
|
||
|---------|------------|
|
||
| Login IP not allowed | Run on the tenant server, or set `CURL_PROXY` to Termius SOCKS |
|
||
| Try again later | Wait; reuse cache; do not `--force-login` |
|
||
| `نوع خودرو یافت نشد` | Set `VEHICLE_KIND_ID` from **this** tenant’s `vehicle-kinds` lookup |
|
||
| File type lookup mismatch | Set `CLAIM_FILE_TYPE_ID` from this tenant’s `file-types` |
|
||
| No `authenticationToken` | Read `login.body.json` in the run folder — Fanavaran `Message` is the real error |
|
||
|
||
## Unit / service specs
|
||
|
||
| Spec | Focus |
|
||
|------|-------|
|
||
| `src/fanavaran/fanavaran-auth.service.spec.ts` | Token cache / midnight / backoff |
|
||
| `src/claim-request-management/fanavaran-policy-selection.spec.ts` | Latest active policy selection |
|
||
|
||
Prefer mocks for Fanavaran HTTP in unit tests; use live calls only in controlled integration.
|
||
|
||
## Manual E2E (Parsian template — via YARA)
|
||
|
||
1. Create THIRD_PARTY claim with guilty party national code that has an **active** Fanavaran policy.
|
||
2. Confirm history `FANAVARAN_EARLY_AUTO_SUBMIT_SUCCEEDED` and `claimId`/`claimNo`.
|
||
3. Select outer parts → `dmgCaseId` set.
|
||
4. Upload images → attachment file ids under `fanavaranSync.attachments`.
|
||
5. Submit expert pricing → `expertiseId`.
|
||
6. Cross-check `fanavaranAuditLogs` for each stage.
|
||
|
||
Preview first if debugging:
|
||
|
||
```http
|
||
GET /v2/fanavaran/parsian/claim-cases/{id}/base-claim/preview?debug=true
|
||
GET /v2/fanavaran/parsian/claim-cases/{id}/damage-case/preview
|
||
GET /v2/fanavaran/parsian/claim-cases/{id}/attachments/preview
|
||
GET /v2/fanavaran/parsian/claim-cases/{id}/expertise/preview
|
||
```
|
||
|
||
## Success scenarios
|
||
|
||
| Scenario | Expect |
|
||
|----------|--------|
|
||
| Happy path Parsian | All four stages succeed |
|
||
| Re-preview after PolicyId cached | No new policy inquiry |
|
||
| Soft-ensure | Damage submit creates base if missing |
|
||
| Skip duplicate base | Second auto-submit skipped when claimId exists |
|
||
|
||
## Error scenarios
|
||
|
||
| Scenario | Expect |
|
||
|----------|--------|
|
||
| Expired policy | Clear BadRequest; no create |
|
||
| Wrong FileTypeId (e.g. 70 on Parsian) | Attachment fail message about lookup |
|
||
| Transient try-later | Backoff; delayed retry; no login storm |
|
||
| Fanavaran down on auto-submit | Local claim continues; history FAILED; manual retry path in warning |
|
||
|
||
## Proven reference case (Parsian)
|
||
|
||
| Local | Fanavaran |
|
||
|-------|-----------|
|
||
| `CL68535` / `A00153` / `_id` `6a707a3a8f4c6fbd851cfa75` | — |
|
||
| Base | `claimId=4909952`, `claimNo=1632`, `policyId=13764408` |
|
||
| Damage | `dmgCaseId=427594`, `DriverId=2426953` |
|
||
| Attachments | FileTypeId **63**; file ids `4629737`… |
|
||
| Expertise | `expertiseId=403144`, assessor `29` |
|
||
|
||
Defaults used: GEN.03 expert `154`, GEN.08 `29`, Location `210050`, InsuranceCorpId `329`, VehicleKindId `6704`.
|
||
|
||
## Mocks
|
||
|
||
- Mock `HttpService` / axios for auth + submit in unit tests.
|
||
- Offline plate/driver seeds for local payload builds without live inquiry (used in proven Parsian offline+live mix).
|
||
- Do not commit live tokens.
|
||
|
||
## Curl catalogue
|
||
|
||
Operational curl sequences (auth, lookups, sample submits): [`docs/external-api-curls.md`](../external-api-curls.md).
|