@testin-official/xagent 0.3.12 → 0.3.14

package/README.md

@@ -47,12 +47,72 @@ xagent run D:\Py\xagent-cli\examples\smoke.yaml --package-id OTHER_PACKAGE_ID --
 Project CI flow:
 
 ```powershell
-xagent init --upload-base-url https://files.example --token-type project_ci --name ci --token-env XAGENT_CI_TOKEN
+xagent init --base-url https://api.example --upload-base-url https://files.example --token-type project_ci --name ci --token-env XAGENT_CI_TOKEN
+xagent --json --profile ci --config .\xagent.yaml targets preview android-single --require-available
 xagent --json --profile ci apps upload .\app-debug.apk
-xagent --json --profile ci --config .\xagent.yaml run .\tests\smoke.yaml --target android-single --app-upload-id APP_UPLOAD_ID --idempotency-key PIPELINE_KEY --wait
+xagent --json --profile ci --config .\xagent.yaml run .\tests\smoke.yaml --target android-single --app-upload-id APP_UPLOAD_ID --idempotency-key JOB_KEY --timeout-ms 600000 --device-wait-timeout-ms 600000 --wait --wait-timeout 1500 --run-id-file .xagent\run_id --output .xagent\run.json --junit .xagent\junit.xml
+# cleanup (after_script / finally)
+xagent --json --profile ci runs cancel RUN_ID --if-active
 xagent --json --profile ci apps release APP_UPLOAD_ID
 ```
 
+A CI job must set both `--base-url` and `--upload-base-url` explicitly; the
+defaults point to the production service.
+
+- `targets preview --require-available` exits with `device_unavailable` (5)
+  when fewer devices are currently available than the Target requests, so the
+  job can stop before building. The preview lists the devices that would be
+  assigned, plus `requested_count`, `matched_count`, and `available_count`.
+- Derive the idempotency key from the CI job ID (for example
+  `gitlab-$CI_PROJECT_ID-$CI_JOB_ID`, or
+  `github-$GITHUB_REPOSITORY_ID-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT-$GITHUB_JOB`).
+  A retried job gets a new ID and a new Run. A key reused with a new
+  `app_upload_id` is rejected with `idempotency_conflict` (2).
+- Keep the timeouts ordered: `--device-wait-timeout-ms` (queue for a busy
+  device; default 10 minutes, `0` to fail immediately) plus `--timeout-ms`
+  (cloud execution) should be shorter than `--wait-timeout` (CLI wait), and
+  all of that should fit inside the CI job timeout. `run --wait` warns when
+  the wait is not longer than the device wait plus the Run timeout. A
+  device-wait timeout finishes as `infrastructure_failed` with
+  `reason=device_wait_timeout` and exit code 5. `targets preview
+  --require-available` still fails before compile when the Target cannot
+  start immediately, including a matrix that does not have enough free devices.
+- `--run-id-file` is written right after the Run is created, so cleanup can
+  cancel it with `runs cancel --if-active`, which skips Runs that are already
+  terminal or cancelling. `--output` holds the last known Run JSON, including when
+  the wait times out. `--junit` writes a standard JUnit XML report for the same
+  Run (one script = one testcase). Failed cases include the assertion step
+  message. The file is written from the last known Run, including when the wait
+  times out.
+
+GitLab can publish the report on the merge request test page:
+
+```yaml
+artifacts:
+  when: always
+  paths:
+    - .xagent/run.json
+    - .xagent/junit.xml
+  reports:
+    junit: .xagent/junit.xml
+```
+
+GitHub Actions can upload the same file and pass it to a JUnit report action:
+
+```yaml
+- name: Upload XAgent JUnit report
+  if: always()
+  uses: actions/upload-artifact@v4
+  with:
+    name: xagent-junit
+    path: .xagent/junit.xml
+- name: Publish XAgent JUnit report
+  if: always()
+  uses: EnricoMi/publish-unit-test-result-action@v2
+  with:
+    files: .xagent/junit.xml
+```
+
 File-service upload requests default to a 15-minute timeout. Override it when needed with
 `xagent apps upload .\app-debug.apk --upload-timeout 900` or
 `xagent run tests\smoke.yaml --apk .\app-debug.apk --device-id DEVICE_001 --upload-timeout 900`.
@@ -60,6 +120,42 @@ File-service upload requests default to a 15-minute timeout. Override it when ne
 `apps upload` and `apps release` require a newly issued `project_ci` Token with
 the `app:upload` capability. One upload can be bound to one Run. Release is
 idempotent and should run from CI cleanup (`after_script` / `finally`).
+
+To run several scripts in one CI job, promote the upload once, then pass a
+directory (or multiple YAML files) to `run`. The CLI starts a Build when you
+pass `--build auto`, attaches each script as a Run, and reuses the same
+`package_id` so the APK is not uploaded again. Derived idempotency keys are
+`<job-key>:<relative-path>:<target>` (the suffix is hashed if the key would
+exceed 255 characters). `--max-parallel` defaults to 1 and only limits how
+many scripts the CLI submits at once. A Target may name up to 20 fixed
+devices or up to 10 filters (`count` 1-10, `concurrency` 1-20). The service
+expands that matrix into one single-device Run per device under the same
+build; `concurrency` is how many of those Runs may occupy a device at the
+same time, and the rest wait using the device-wait queue. A matrix Target requires
+`--package-id` (or `--app-upload-id --promote`) and a build; `run` starts
+one automatically when you omit `--build-id` and `--build auto`.
+
+```powershell
+xagent --json --profile ci apps upload .\app-debug.apk --promote
+xagent --json --profile ci --config .\xagent.yaml run .\tests --target android-single --package-id PACKAGE_ID --build auto --idempotency-key JOB_KEY --timeout-ms 600000 --device-wait-timeout-ms 600000 --wait --wait-timeout 1500 --output .xagent\run.json --junit .xagent\junit.xml
+# cleanup (after_script / finally)
+xagent --json --profile ci builds cancel BUILD_ID --if-active
+```
+
+`--build auto` infers the build name, commit, and pipeline URL from GitLab CI
+or GitHub Actions environment variables. You can also pass an existing
+`--build-id`, or manage the same resource with `builds start`, `builds show`,
+`builds wait`, and `builds cancel`. A multi-script `--junit` (or
+`builds wait --junit`) writes a suite report: one `testsuites`, one
+`testsuite` per target, one `testcase` per script and device. A single-script, single-device
+`run --wait --junit` is unchanged. The command's exit code follows the D3
+priority 3 > 2 > 6 > 1 > 7 > 5 > 4 > 0. `--output` for a batch is
+`{ "build_id", "runs": [...] }`.
+
+`apps promote APP_UPLOAD_ID` does the same for an existing upload. A promoted
+package is kept in the project until it is deleted on the platform; `apps release`
+on a promoted upload leaves it in place. A promoted upload can no longer be
+passed as `--app-upload-id`.
 The Profile's `upload_base_url` points to the file service. The CLI sends the
 same Developer Token only to `/app/ci/init`; chunk requests use a short-lived
 upload ticket and never persist the Token in project files.

package/dist/assets/contracts/app-upload.schema.json

@@ -20,7 +20,7 @@
     "id": {"type": "string", "pattern": "^appup_[a-f0-9]{32}$"},
     "package_id": {"type": "integer", "minimum": 1},
     "status": {
-      "enum": ["active", "bound", "release_requested", "released", "expired"]
+      "enum": ["active", "bound", "release_requested", "released", "expired", "promoted"]
     },
     "file_name": {"type": "string", "minLength": 1, "maxLength": 512},
     "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
@@ -40,6 +40,7 @@
     "expires_at": {"type": "string", "format": "date-time"},
     "bound_run_id": {"type": "string", "minLength": 1},
     "release_requested_at": {"type": "string", "format": "date-time"},
-    "released_at": {"type": "string", "format": "date-time"}
+    "released_at": {"type": "string", "format": "date-time"},
+    "promoted_at": {"type": "string", "format": "date-time"}
   }
 }

package/dist/assets/contracts/build-create.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://xagent.testin.cn/schemas/developer/v1/build-create.schema.json",
+  "title": "XAgent Build Create v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version"],
+  "properties": {
+    "schema_version": {"const": "xagent-build-create/v1"},
+    "name": {"type": "string", "minLength": 1, "maxLength": 255},
+    "external_id": {"type": "string", "minLength": 1, "maxLength": 255},
+    "source": {"enum": ["gitlab", "github", "other"]},
+    "commit_sha": {"type": "string", "minLength": 1, "maxLength": 64},
+    "ref": {"type": "string", "minLength": 1, "maxLength": 255},
+    "pipeline_url": {"type": "string", "format": "uri", "maxLength": 1024}
+  }
+}

package/dist/assets/contracts/build-list.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://xagent.testin.cn/schemas/developer/v1/build-list.schema.json",
+  "title": "XAgent Build List v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "builds", "page", "page_size", "total"],
+  "properties": {
+    "schema_version": {"const": "xagent-build-list/v1"},
+    "builds": {
+      "type": "array",
+      "items": {"$ref": "build.schema.json"}
+    },
+    "page": {"type": "integer", "minimum": 1},
+    "page_size": {"type": "integer", "minimum": 1, "maximum": 100},
+    "total": {"type": "integer", "minimum": 0}
+  }
+}

package/dist/assets/contracts/build.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://xagent.testin.cn/schemas/developer/v1/build.schema.json",
+  "title": "XAgent Build v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "id",
+    "status",
+    "name",
+    "closed",
+    "cancel_requested",
+    "created_at",
+    "runs"
+  ],
+  "properties": {
+    "schema_version": {"const": "xagent-build/v1"},
+    "id": {"type": "string", "pattern": "^bld_[a-f0-9]{32}$"},
+    "status": {
+      "enum": [
+        "running",
+        "passed",
+        "failed",
+        "infrastructure_failed",
+        "cancelled",
+        "timed_out"
+      ]
+    },
+    "name": {"type": "string", "minLength": 1, "maxLength": 255},
+    "external_id": {"type": "string", "minLength": 1, "maxLength": 255},
+    "source": {"enum": ["gitlab", "github", "other"]},
+    "commit_sha": {"type": "string", "minLength": 1, "maxLength": 64},
+    "ref": {"type": "string", "minLength": 1, "maxLength": 255},
+    "pipeline_url": {"type": "string", "format": "uri", "maxLength": 1024},
+    "closed": {"type": "boolean"},
+    "cancel_requested": {"type": "boolean"},
+    "created_at": {"type": "string", "format": "date-time"},
+    "closed_at": {"type": "string", "format": "date-time"},
+    "runs": {
+      "type": "array",
+      "items": {"$ref": "#/$defs/run_summary"}
+    },
+    "cancel_results": {
+      "type": "array",
+      "items": {"$ref": "#/$defs/cancel_result"}
+    }
+  },
+  "$defs": {
+    "run_summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "status"],
+      "properties": {
+        "id": {"type": "string", "minLength": 1},
+        "script_name": {"type": "string"},
+        "target_name": {"type": "string"},
+        "device_id": {"type": "string"},
+        "device_model": {"type": "string"},
+        "status": {"type": "string", "minLength": 1},
+        "exit_code": {"type": ["integer", "null"], "minimum": 0, "maximum": 7}
+      }
+    },
+    "cancel_result": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "ok"],
+      "properties": {
+        "id": {"type": "string", "minLength": 1},
+        "ok": {"type": "boolean"},
+        "status": {"type": "string"},
+        "error": {"type": "string"}
+      }
+    }
+  }
+}

package/dist/assets/contracts/execution-target.schema.json

@@ -9,17 +9,21 @@
     "device_ids": {
       "type": "array",
       "minItems": 1,
-      "maxItems": 1,
+      "maxItems": 20,
       "uniqueItems": true,
       "items": {"type": "string", "minLength": 1, "maxLength": 128}
     },
     "device_filters": {
       "type": "array",
       "minItems": 1,
-      "maxItems": 1,
+      "maxItems": 10,
       "items": {"$ref": "#/$defs/device_filter"}
     },
-    "concurrency": {"const": 1}
+    "concurrency": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 20
+    }
   },
   "oneOf": [
     {
@@ -41,7 +45,11 @@
         "brand": {"type": "string", "minLength": 1, "maxLength": 128},
         "model": {"type": "string", "minLength": 1, "maxLength": 128},
         "resolution": {"type": "string", "minLength": 1, "maxLength": 64},
-        "count": {"const": 1},
+        "count": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10
+        },
         "strategy": {"enum": ["random", "weight"]}
       },
       "anyOf": [

package/dist/assets/contracts/fixtures/execution-target.concurrency-twenty-one.invalid.json

@@ -0,0 +1,4 @@
+{
+  "device_ids": ["DEVICE_001"],
+  "concurrency": 21
+}

package/dist/assets/contracts/fixtures/execution-target.concurrency-two.invalid.json

@@ -1,4 +1,4 @@
 {
   "device_ids": ["DEVICE_001"],
-  "concurrency": 2
+  "concurrency": 21
 }

package/dist/assets/contracts/fixtures/execution-target.concurrency-two.valid.json

@@ -0,0 +1,4 @@
+{
+  "device_ids": ["DEVICE_001"],
+  "concurrency": 2
+}

package/dist/assets/contracts/fixtures/execution-target.count-eleven.invalid.json

@@ -0,0 +1,6 @@
+{
+  "device_filters": [
+    {"os": "Android", "count": 11, "strategy": "random"}
+  ],
+  "concurrency": 1
+}

package/dist/assets/contracts/fixtures/execution-target.count-two.invalid.json

@@ -1,6 +1,6 @@
 {
   "device_filters": [
-    {"os": "Android", "count": 2, "strategy": "random"}
+    {"os": "Android", "count": 11, "strategy": "random"}
   ],
   "concurrency": 1
 }

package/dist/assets/contracts/fixtures/execution-target.count-two.valid.json

@@ -0,0 +1,6 @@
+{
+  "device_filters": [
+    {"os": "Android", "count": 2, "strategy": "random"}
+  ],
+  "concurrency": 2
+}

package/dist/assets/contracts/fixtures/execution-target.multiple-devices.invalid.json

@@ -1,4 +1,26 @@
 {
-  "device_ids": ["DEVICE_001", "DEVICE_002"],
+  "device_ids": [
+    "DEVICE_001",
+    "DEVICE_002",
+    "DEVICE_003",
+    "DEVICE_004",
+    "DEVICE_005",
+    "DEVICE_006",
+    "DEVICE_007",
+    "DEVICE_008",
+    "DEVICE_009",
+    "DEVICE_010",
+    "DEVICE_011",
+    "DEVICE_012",
+    "DEVICE_013",
+    "DEVICE_014",
+    "DEVICE_015",
+    "DEVICE_016",
+    "DEVICE_017",
+    "DEVICE_018",
+    "DEVICE_019",
+    "DEVICE_020",
+    "DEVICE_021"
+  ],
   "concurrency": 1
 }

package/dist/assets/contracts/fixtures/execution-target.multiple-devices.valid.json

@@ -0,0 +1,4 @@
+{
+  "device_ids": ["DEVICE_001", "DEVICE_002"],
+  "concurrency": 1
+}

package/dist/assets/contracts/fixtures/execution-target.multiple-filters.invalid.json

@@ -1,7 +1,71 @@
 {
   "device_filters": [
-    {"os": "Android", "brand": "Huawei", "count": 1, "strategy": "weight"},
-    {"os": "Android", "brand": "Samsung", "count": 1, "strategy": "weight"}
+    {
+      "os": "Android",
+      "brand": "Brand1",
+      "count": 1,
+      "strategy": "weight"
+    },
+    {
+      "os": "Android",
+      "brand": "Brand2",
+      "count": 1,
+      "strategy": "weight"
+    },
+    {
+      "os": "Android",
+      "brand": "Brand3",
+      "count": 1,
+      "strategy": "weight"
+    },
+    {
+      "os": "Android",
+      "brand": "Brand4",
+      "count": 1,
+      "strategy": "weight"
+    },
+    {
+      "os": "Android",
+      "brand": "Brand5",
+      "count": 1,
+      "strategy": "weight"
+    },
+    {
+      "os": "Android",
+      "brand": "Brand6",
+      "count": 1,
+      "strategy": "weight"
+    },
+    {
+      "os": "Android",
+      "brand": "Brand7",
+      "count": 1,
+      "strategy": "weight"
+    },
+    {
+      "os": "Android",
+      "brand": "Brand8",
+      "count": 1,
+      "strategy": "weight"
+    },
+    {
+      "os": "Android",
+      "brand": "Brand9",
+      "count": 1,
+      "strategy": "weight"
+    },
+    {
+      "os": "Android",
+      "brand": "Brand10",
+      "count": 1,
+      "strategy": "weight"
+    },
+    {
+      "os": "Android",
+      "brand": "Brand11",
+      "count": 1,
+      "strategy": "weight"
+    }
   ],
   "concurrency": 1
 }

package/dist/assets/contracts/fixtures/execution-target.multiple-filters.valid.json

@@ -0,0 +1,7 @@
+{
+  "device_filters": [
+    {"os": "Android", "brand": "Huawei", "count": 1, "strategy": "weight"},
+    {"os": "Android", "brand": "Samsung", "count": 1, "strategy": "weight"}
+  ],
+  "concurrency": 2
+}

package/dist/assets/contracts/fixtures/target-hash-cases.json

@@ -3,7 +3,9 @@
     {
       "name": "fixed_device",
       "target": {
-        "device_ids": ["DEVICE_001"],
+        "device_ids": [
+          "DEVICE_001"
+        ],
         "concurrency": 1
       },
       "canonical_json": "{\"concurrency\":1,\"device_ids\":[\"DEVICE_001\"]}",
@@ -25,6 +27,55 @@
       },
       "canonical_json": "{\"concurrency\":1,\"device_filters\":[{\"brand\":\"Huawei\",\"count\":1,\"model\":\"P30\",\"os\":\"Android\",\"strategy\":\"weight\"}]}",
       "target_hash": "b57ee824993af6958955bdc74793c256efb47dcc26f4338dd2f265b3b9b7d901"
+    },
+    {
+      "name": "multiple_devices",
+      "target": {
+        "device_ids": [
+          "DEVICE_001",
+          "DEVICE_002"
+        ],
+        "concurrency": 1
+      },
+      "canonical_json": "{\"concurrency\":1,\"device_ids\":[\"DEVICE_001\",\"DEVICE_002\"]}",
+      "target_hash": "80870e64fa03e302a192ccfc933272a764ee1ec62f5d7fad517e70562d7d213a"
+    },
+    {
+      "name": "count_two",
+      "target": {
+        "device_filters": [
+          {
+            "os": "Android",
+            "count": 2,
+            "strategy": "random"
+          }
+        ],
+        "concurrency": 2
+      },
+      "canonical_json": "{\"concurrency\":2,\"device_filters\":[{\"count\":2,\"os\":\"Android\",\"strategy\":\"random\"}]}",
+      "target_hash": "42c254c3600ba7d4fedb10eb33110964149ed630f967c470a8c711532afdd6e1"
+    },
+    {
+      "name": "multiple_filters",
+      "target": {
+        "device_filters": [
+          {
+            "os": "Android",
+            "brand": "Huawei",
+            "count": 1,
+            "strategy": "weight"
+          },
+          {
+            "os": "Android",
+            "brand": "Samsung",
+            "count": 1,
+            "strategy": "weight"
+          }
+        ],
+        "concurrency": 2
+      },
+      "canonical_json": "{\"concurrency\":2,\"device_filters\":[{\"brand\":\"Huawei\",\"count\":1,\"os\":\"Android\",\"strategy\":\"weight\"},{\"brand\":\"Samsung\",\"count\":1,\"os\":\"Android\",\"strategy\":\"weight\"}]}",
+      "target_hash": "aa07c6fe0cba4ed2feda2982988278304820a0e8069d75bb2d9a27941ba0ccad"
     }
   ]
 }

package/dist/assets/contracts/fixtures/target-preview.success.json

@@ -14,5 +14,8 @@
     }
   ],
   "previewed_at": "2026-07-31T08:00:00Z",
-  "reserved": false
+  "reserved": false,
+  "requested_count": 1,
+  "matched_count": 1,
+  "available_count": 1
 }

package/dist/assets/contracts/fixtures/target-preview.unavailable.json

@@ -14,5 +14,8 @@
     }
   ],
   "previewed_at": "2026-07-31T08:00:00Z",
-  "reserved": false
+  "reserved": false,
+  "requested_count": 1,
+  "matched_count": 1,
+  "available_count": 0
 }

package/dist/assets/contracts/run-create-result.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://xagent.testin.cn/schemas/developer/v1/run-create-result.schema.json",
+  "title": "XAgent Run Create Result v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "build_id", "runs"],
+  "properties": {
+    "schema_version": {"const": "xagent-run-create-result/v1"},
+    "build_id": {"type": "string", "pattern": "^bld_[a-f0-9]{32}$"},
+    "runs": {
+      "type": "array",
+      "minItems": 2,
+      "maxItems": 100,
+      "items": {"$ref": "run.schema.json"}
+    }
+  }
+}