@testin-official/xagent 0.3.13 → 0.3.14

package/README.md

@@ -50,7 +50,7 @@ Project CI flow:
 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 JOB_KEY --timeout-ms 600000 --wait --wait-timeout 720 --run-id-file .xagent\run_id --output .xagent\run.json
+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
@@ -60,19 +60,58 @@ 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 no previewed device is available, so the job can stop before building.
+  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: `--timeout-ms` (cloud Run) is shorter than
-  `--wait-timeout` (CLI wait), and both fit inside the CI job timeout. `run --wait`
-  warns when the wait is not longer than the Run timeout.
+- 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.
+  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
@@ -82,15 +121,37 @@ File-service upload requests default to a 15-minute timeout. Override it when ne
 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 against one build, promote the upload and pass its
-`package_id` to every Run instead of `--app-upload-id`:
+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\login.yaml --target android-single --package-id PACKAGE_ID --idempotency-key JOB_KEY-login --wait
-xagent --json --profile ci --config .\xagent.yaml run .\tests\checkout.yaml --target android-single --package-id PACKAGE_ID --idempotency-key JOB_KEY-checkout --wait
+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

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"}
+    }
+  }
+}