Skip to main content

How Device Fulfillment Works

When you ask TV Labs for a device, whether from WebDriver, the CLI, an automation, or the website, your request goes into a queue. It waits there until a device that satisfies it becomes free. This guide explains how requests are matched to devices, why some requests wait longer than others, and what you can do to get a specific platform variant faster.

The life of a request​

  1. License. TV Labs checks out one of your organization's licenses. If none is free, the request waits for one, up to the tvlabs:licensing_timeout for WebDriver sessions.
  2. Queue. The request joins the queue for its platform (for example android_tv or entertainment_os). Each platform has its own queue, so a backlog on Roku never delays a Tizen request.
  3. Prewarm. While the request waits, TV Labs may start warming up several idle devices that match it at the same time, so one is ready sooner once a device is assigned.
  4. Match. When a device on that platform becomes free, it is offered to waiting requests in priority order (see Queue order). The first request the device is eligible for gets it.
  5. Warmup. The matched device is prepared, if prewarming has not already done it: powered on, connected, and given your build if you requested one. For WebDriver sessions this is bounded by tvlabs:device_timeout.
  6. Timeout. If no device matches before the request's deadline, the request is canceled. For WebDriver sessions the deadline is tvlabs:match_timeout, which defaults to 5 minutes through the Appium proxy and 15 minutes through the WebDriverIO service.

Which devices can serve a request​

A device can serve your request only when all of the following are true:

  • It is healthy.
  • It is free, meaning no other session is using it.
  • Your organization has access to it. Not every organization can use every device in the TV Labs fleet; which devices you can use depends on your plan.
  • If it is reserved behind tags, your request opts into every one of them. Tagged devices only serve requests that name their tags, and a request that names tags only matches devices that carry all of them.
  • If it is dedicated, it is dedicated to your organization. Dedicated devices are eligible only for the organization they belong to.
  • It satisfies every term in your tvlabs:constraints, including platform_os_variant, model, year, and any version fields.

Every term you add to your constraints shrinks the set of devices that can serve you. A request for platform_key:android_tv can be served by any healthy Android TV device in your plan. Adding platform_os_variant:fire_tv AND year>=2024 AND fire_version>=8 may leave only a handful.

Platform OS variants​

A platform OS variant (for example fire_tv or stock on android_tv, or sky and xumo on entertainment_os) is a property of the device model. See the platforms table for the available values.

  • Without platform_os_variant, any variant of the platform can serve the request.
  • With platform_os_variant, only devices of that variant can.
  • If your organization's license is scoped to a variant and the request doesn't name one, the license's variant is applied to the request.

Requests that can never be filled​

If your constraints name a valid platform_key but no device in your plan matches them, the request does not fail immediately. It waits in the queue until its deadline, in case a matching device comes online. A misspelled platform key or an unknown version field is rejected as soon as you make the request.

If a request reliably runs out its full match_timeout, check that devices matching your constraints actually exist. Browse the device catalog, or contact us with the constraints you are using.

Queue order​

Requests on a platform are considered in this order:

  1. Interactive sessions on the TV Labs website, including embedded sessions and CLI execute sessions.
  2. Automations started by a person.
  3. WebDriver sessions and scheduled automations.

Within each group, the oldest request goes first.

A free device goes to the first request in this order that it can serve. Your specific request never blocks a broader request behind it: a device that doesn't match you passes you by and serves the next request. But a broad request ahead of you can take a device that matches your specific request. When many broad requests are queued for a platform, devices of a scarce variant are shared among all of them, not held for requests that name that variant.

Getting a specific variant faster​

Fulfillment depends on how many free devices match your request compared with how many requests are competing for them. Each lever below changes one side of that.

Constrain only what your test depends on​

  • Leave out platform_os_variant if your test runs on any variant of the platform.
  • Prefer ranges to exact values: os_version>=8.0 matches more devices than os_version:8.0.1.
  • Use glob patterns for families of models: model:(C* OR UT*) instead of one model.
  • Drop year or make when they don't affect the behavior under test.

Size concurrency to the variant, not the platform​

If 50 parallel WebDriver sessions all target a variant with far fewer devices, most of them wait, and they also compete with every other request on that platform. Limit your test runner's parallelism for narrow targets, or spread those runs out over time.

Set timeouts to match your expectations​

Raise tvlabs:match_timeout for scarce variants that you are willing to wait for. Lower it when you would rather fail fast and retry later. Make sure your WebDriver client's own request timeout is longer than match_timeout plus device_timeout, or the client gives up before TV Labs does.

Reserve capacity with dedicated devices​

Dedicated devices belong to your organization alone, so no other customer competes for them. This is the most reliable way to guarantee access to a particular variant or model. Use tags to keep a set of devices for a specific program or team.

note

Licenses control how many sessions your organization can run at once. They do not reserve devices. A license scoped to a platform or variant guarantees you can start a session of that kind, but the request still waits for a matching device to be free.

Ask us to add devices​

If requests for a variant you depend on are consistently difficult to match with, contact [email protected] with:

  • the platform, variant, and models you need,
  • how many sessions you expect to run at once, and
  • the constraints your tests use.

We use this to decide what hardware to add to the shared fleet or to propose dedicated devices.