Functional Testing: Engines
Overview
Use this page to enroll and monitor functional testing engines. An engine is a Windows host running LoadGen FunctionalEngine.exe in platform mode: it enrolls with a one-time token, then claims runs, uploads result rows and screenshots, and reports a regular heartbeat. Without at least one enrolled engine, functional test packages and schedules have no host to execute on.
Before you enroll an engine, you install the matching FunctionalEngine build, published from the appliance's software updates, on a Windows host you control. Once an engine is online, functional test packages and schedules assign it runs; the rows, screenshots, and results it uploads then show up in run history. SystemTesting testcases additionally need the host kept on a logged-on interactive desktop.
This page lets you generate and revoke enrollment tokens, watch each engine's installed build, capability, state, and last heartbeat in one table, and edit an engine's name, tags, and desired state. You can also rotate an engine's key or remove it entirely when a host is retired.
Key concepts
- engine - A Windows host running LoadGen FunctionalEngine.exe in platform mode. It enrolls with a token, then claims runs, uploads result rows and screenshots, and reports a regular heartbeat. (related: Functional Testing: Run History)
- enrollment token - A short-lived credential you generate on this page that lets a Windows host register itself as an engine. Its secret and enroll command are shown only once, when the token is created.
- desired state - An administrative setting on each engine, changed from the Edit engine dialog, that controls whether the platform keeps the engine available to claim new runs.
- SystemTesting testcase - A functional testcase that requires a logged-on interactive Windows desktop session on the engine's host to run, rather than running headless. (related: Functional Testing: Packages)
- heartbeat - The periodic check-in an engine sends to report that it is alive. The Heartbeat column shows how long ago the last one arrived.
When to use it
- You need to add a new Windows host as an engine so a functional test package or schedule has somewhere to run.
- You want to check how many engines are currently Online, Busy, or Offline before scheduling a run.
- An engine's key may be compromised, or the host was reimaged, and it needs a new key.
- A host is being decommissioned and its engine record should be removed.
- An enrollment token is no longer needed, or may have leaked, and must be revoked before it expires.
- You want to confirm which engines are running an outdated FunctionalEngine build before an update.
Before you begin
- A Windows host set aside to run FunctionalEngine.exe, kept on a logged-on interactive desktop if it will run SystemTesting testcases.
- The matching FunctionalEngine installer, downloaded from the appliance's software updates (Infrastructure: Appliance).
- Account permissions for Functional Testing engine management; writes on this page are only offered to a role with the matching grant.
- Functional test packages or schedules ready to assign work to the engine once it is online (Functional Testing: Packages, Functional Testing: Schedules).
Common workflows
Enroll a new Windows host as an engine
Persona: Functional testing operator
- Select New enrollment token in the toolbar.
- Expect: The New enrollment token dialog opens with fields for Name, Expires in (hours), Engines it may enroll, and Tags given to every engine it enrolls.
- Enter a Name, set Expires in (hours) and Engines it may enroll as needed, then create the token.
- Expect: The dialog shows the token's secret and its enroll command; both are shown exactly once and will not be shown again once the dialog closes.
- Run the displayed enroll command in an elevated prompt on the target Windows host.
- Expect: The host enrolls, and after its next heartbeat a new row appears in the engines table with its OS, Build, and State.
- Select Refresh.
- Expect: The engines table reloads, and the Enrolled and Online KPI tiles each increase by one once the new engine has reported in.
Verify: The new engine appears in the table with State Online and a recent Heartbeat, and the Enrolled and Online KPI tiles both read at least 1.
Rotate a compromised engine's key
Persona: Administrator
- Select Rotate key on the engine's row.
- Expect: A confirmation step opens before the key is rotated.
- Confirm the rotation.
- Expect: The Rotated key dialog shows the new engine key once, and the engine's previous key stops authenticating immediately.
- Apply the new key in FunctionalEngine's configuration on the Windows host and restart the service.
- Expect: The engine reconnects, and its Heartbeat and State update to reflect it is online again.
Verify: The engine's State returns to Online with a fresh Heartbeat timestamp after the restart; if it stays Offline, the new key was not applied on the host.
Steps
Step 1
Open Engines under Functional Testing.
Expected result: The page loads in its starting state: all four KPI tiles, Enrolled, Online, Busy, and Offline, read 0, and the engines table shows the message that no engine is enrolled yet.
This is the starting point for enrolling your first engine so functional test packages and schedules have a host to run on.
- The Refresh and New enrollment token buttons sit in the toolbar above the table.
- The info panel explains where to download the FunctionalEngine build and links to Software updates.
- The Enrollment tokens panel at the bottom is where you create tokens and later revoke them.
Field reference
| Field | Purpose | Format / Validation | Required | Default |
|---|---|---|---|---|
| Name | Identifies this enrollment token in the Enrollment tokens list, so you can tell separate rollout batches apart. | text | Yes | - |
| Expires in (hours) | Sets how long the token stays valid for enrolling engines. A short value close to the 1-hour minimum limits how long a leaked token could be reused; a longer value, up to 720 hours (30 days), suits staged rollouts where hosts are enrolled over several days. | number (hours) | Yes | 24 |
| Engines it may enroll | Caps how many separate Windows hosts can use this one token before it stops working. Set it to 1 to issue a single-use token for one host, or higher to enroll a batch of hosts with the same enroll command. | number | Yes | 1 |
| Tags given to every engine it enrolls | Labels applied automatically to every engine that enrolls with this token, so you can group or filter engines by lab, team, or environment without tagging each host by hand. | tag list | No | - |
| Name (Edit engine) | Renames the engine as it appears in the Engine column. Use a name that identifies the host, since the token's own Name does not carry over to the engines it enrolls. | text | Yes | The name set at enrollment |
| Tags (Edit engine) | Free-form labels on this individual engine, used the same way as token tags, for grouping or filtering engines in the table. | tag list | No | Inherited from the enrollment token used |
| Desired state | Determines whether the platform keeps this engine available to claim new runs. Change it from its default when you need to hold a host back from new work, for example during maintenance, without removing it from the list. | dropdown | Yes | Enabled |
Column reference
| Column | What it shows | How to read it |
|---|---|---|
| Engine | The engine's display name. | Shows the name given to the host at enrollment, or a later rename from the Edit engine dialog. |
| OS | The operating system reported by the engine's host. | Read it to confirm the host meets the OS requirements for the packages you plan to run on it. |
| Build | The installed FunctionalEngine build on the host. | An update chip appears when a newer build is published in the appliance's software updates, telling you this engine needs updating before its next heartbeat offers the new build. |
| Can run | What kind of testcases this engine is currently able to execute. | An engine without a logged-on interactive desktop session cannot run SystemTesting testcases that require one, regardless of its State. |
| State | The engine's current availability. | Online means the engine is enrolled and reachable, Busy means it currently holds a run, and Offline means it has missed its expected heartbeat. |
| Heartbeat | When the engine last reported in. | Shows how long ago the last report arrived and refreshes automatically; hover it for the exact timestamp. If it stops advancing, treat the engine as unreachable even if State has not updated yet. |
| Actions | Row-level controls for this engine. | Holds the Edit, Rotate key, and Remove buttons for that engine, and a Current run link when the engine holds a run. |
| Enrolled | Total engines enrolled. | Counts every engine regardless of state; stays at 0 until the first engine completes enrollment. |
| Online | Engines currently reachable and idle. | Rises as engines report a heartbeat with nothing assigned; check this before scheduling a run that needs free capacity. |
| Busy | Engines currently holding a run. | A non-zero value means that many engines are unavailable for a new run until their current one finishes. |
| Offline | Engines that have missed their expected heartbeat. | A rising count signals hosts that have lost network access or stopped the FunctionalEngine service; cross-check against the Heartbeat column to find which ones. |
Controls reference
Refresh
Reloads the engines list and enrollment tokens list from the server.
When to use: After running an enroll command, rotating a key, or whenever the Heartbeat or State values look stale and you don't want to wait for the automatic re-render.
Side effects: Read-only: reloads displayed data without changing anything.
New enrollment token
Opens the New enrollment token dialog to generate a token and the one-time enroll command for a new Windows host. The same action is offered both in the page toolbar and inside the Enrollment tokens panel.
When to use: Before installing FunctionalEngine.exe on a host you want to add as an engine.
Side effects: Mutating: creates a new enrollment token record. Its secret and enroll command are shown only once, in this dialog.
Software updates
Navigates to the appliance's software updates, where the FunctionalEngine build engines update to is published.
When to use: Before enrolling a new host, to download the matching installer.
Side effects: Read-only navigation away from this page.
Edit
Opens the Edit engine dialog for that row, pre-filled with the engine's current Name, Tags, and Desired state.
When to use: To rename an engine, retag it, or change its desired state.
Side effects: Opens a dialog only; no data changes until you save.
Save
Commits the Name, Tags, and Desired state changes made in the Edit engine dialog.
When to use: After changing any field in the Edit engine dialog.
Side effects: Mutating: updates the engine record and shows a confirmation that the engine was saved.
Rotate key
Issues a new authentication key for that engine and shows it once in a Rotated key dialog.
When to use: When an engine's key may be compromised, or the host was reimaged and must re-authenticate.
Side effects: Mutating: the engine's previous key stops authenticating immediately, so the host cannot check in again until the new key is applied on it.
Remove
Deletes the engine record entirely, after a confirmation step.
When to use: When decommissioning a host that no longer runs FunctionalEngine.
Side effects: Mutating and permanent: the engine disappears from the table and a confirmation message shows it was removed.
Current run
Opens the run that engine currently holds.
When to use: To inspect what a Busy engine is executing right now.
Side effects: Read-only navigation; only shown on an engine's row while it holds a run.
Revoke
Invalidates an enrollment token before it expires, after a confirmation step.
When to use: When a token is no longer needed, or may have leaked.
Side effects: Mutating: the token can no longer be used to enroll further engines; a confirmation message shows it was revoked.
Verify the result
Once an engine has enrolled, its row appears in the engines table with the host's OS, installed Build, and a Can run value, and its State reads Online with a recent Heartbeat. The Enrolled and Online KPI tiles rise from 0 to reflect each engine that has checked in. If the table still shows the no-engine message after running the enroll command, select Refresh and check whether the token had already expired or reached its Engines it may enroll limit. A Build cell carrying an update chip means that engine is running an older FunctionalEngine build than the one published in the appliance's software updates.
Troubleshooting
- Symptom: The engines table still shows "No engine is enrolled yet" after running the enroll command. Fix: Select Refresh; if it still does not appear, confirm the command ran in an elevated prompt on the target host and that the token had not already expired or reached its Engines it may enroll limit.
- Symptom: An engine's State shows Offline even though the host is powered on. Fix: Check the Heartbeat column; FunctionalEngine reports regularly, so a Heartbeat older than a few minutes means the service has stopped or lost network access, not a display delay.
- Symptom: A SystemTesting testcase will not claim this engine even though its State is Online. Fix: Confirm the Windows host has an interactive desktop session logged on; SystemTesting testcases cannot run on an engine without one, regardless of State.
- Symptom: You can't recover a token's secret or enroll command after closing the New enrollment token dialog. Fix: Both are shown only once by design; select New enrollment token again and issue a new token instead.
- Symptom: New enrollment token, Edit, Rotate key, Remove, or Revoke are missing or disabled. Fix: These writes are only offered to a role with the matching grant; check your account's permissions for Functional Testing engine management.
Related articles
- Prerequisite: Functional Testing: Packages - packages define the testcases an engine claims and runs
- Prerequisite: Functional Testing: Schedules - schedules determine when engines are assigned runs
- Next step: Functional Testing: Run History - review the runs an engine has executed
- Prerequisite: Infrastructure: Appliance - the FunctionalEngine installer is published from the appliance's software updates
- See also: Functional Testing: Dashboard - overview of functional testing activity across engines and packages