UI Tests API Reference

Create a UI Test

POST /api/ui-tests

Body:

{
  "name": "Login Flow Test",
  "projectId": 1,
  "yamlContent": "steps:\n  - action: NAVIGATE_TO\n    value: \"{{baseUrl}}\"\n  - action: TAKE_SCREENSHOT"
}

Note: targetId is NOT part of the create request. The target is specified when running the test.

Optional fields: description, driver (WEBDRIVER or PLAYWRIGHT), feature, tags, groupName

---

Run a UI Test

POST /api/ui-tests/{id}/run

Body:

{
  "target": "http://user-service-ui",
  "environmentId": 1,
  "credentialTag": "admin",
  "tag": "smoke-v1",
  "browsers": ["chrome"]
}

Field	Required	Description
target	Yes	Target URL to run against
environmentId	No	Environment for credential resolution
credentialTag	No	Specific credential tag (uses default if omitted)
tag	No	Execution tag for filtering
browsers	No	Array for multi-browser matrix: ["chrome","firefox","webkit"]

Response:

{
  "testId": 14,
  "testName": "Login Flow Test",
  "target": "http://user-service-ui",
  "jobId": "74e2d109-fb92-478a-a719-bebda6b2a342",
  "browser": "chrome",
  "status": "PENDING"
}

---

List UI Tests

GET /api/ui-tests?projectId=1

---

Get UI Test

GET /api/ui-tests/{id}

---

Delete UI Test

DELETE /api/ui-tests/{id}

Soft-deletes the test by setting status to ARCHIVED. The test is still accessible via GET but excluded from active lists. Returns 204 No Content.

---

Link Environment to Project

POST /api/projects/{projectId}/environments/{environmentId}

No request body needed. Environment ID is in the URL path.

Response: Returns the project object with linked environments.

---

Add Target to Environment

POST /api/environments/{environmentId}/targets

Body:

{
  "name": "User Service UI",
  "targetType": "WEB_APP",
  "baseUrl": "{{baseUrl}}",
  "homePageUrl": "http://user-service-ui"
}

Valid target types: REST_SERVICE, WEB_APP, MOBILE_APP, NETWORK, HOSTNAME, GRPC, GRAPHQL

---

Recommend Engine

GET /api/crawl/recommend-engine?targetId={id}
GET /api/crawl/recommend-engine?url={url}

Returns the best crawler engine for the target, based on its detected tech stack. Wizard Step 2 uses this to pre-select Playwright vs HtmlUnit.

Either targetId or url must be supplied. If both are given, targetId takes precedence.

Response:

{
  "engine": "PLAYWRIGHT",
  "confidence": "HIGH",
  "reason": "Next.js __NEXT_DATA__ marker found — Playwright required"
}

Field	Values	Meaning
engine	PLAYWRIGHT, HTMLUNIT	Engine to use for the crawl
confidence	HIGH, MEDIUM, LOW	How sure the recommender is. Clients should ignore LOW (it's effectively "no signal — use the safe default").
reason	Free text	One-line explanation. Safe to surface to users.

Selection logic:

1. If targetId is linked (via appTag) to a project_applications row with application_tech ∈ {REACT, ANGULAR, VUE, NEXT, SVELTE, VITE} → PLAYWRIGHT / HIGH.
2. Otherwise one HTTP GET of the URL, scanning body + headers for SPA markers (Next/Nuxt/Angular/React) and SSR markers (WordPress, PHP, static-site generators).
3. Ambiguous → PLAYWRIGHT / LOW. Playwright is the safe default — wrong "HtmlUnit" misses SPA elements; wrong "Playwright" is just slower.

Gotchas:

• The probe is unauthenticated. Auth-walled landing pages may classify as LOW even if the real app is a SPA. Workaround: link the target to a ProjectApplication so the DB lookup runs before the probe.
• Probe times out at 5 seconds. Slow/unreachable targets fall back to the safe default.
• Environment ↔ Project is many-to-many; if multiple linked projects have an application matching the target's appTag, the first frontend-tech match wins.

---

Execute UI Test Suite

POST /api/ui-test-suites/{id}/run

Body:

{
  "environmentId": 1,
  "credentialTag": "admin",
  "tag": "regression-v1"
}

Credentials are auto-resolved from the environment's default credential if credentialTag is omitted.