tests kit

10 tools. Generated from the plugin source; do not edit by hand.

Guide

Use tests to observe the Automation Controller without starting or waiting for tests, and to author level AFunctionalTest actors. Use edit.list_tests to enumerate the framework registry and edit.run_test or edit.run_tests only when execution is intended.

Start by checking whether the editor has an Automation Controller and whether it has workers or prior reports:

tests.get_automation_status {}
tests.inspect_automation_reports {"contains":"Project","limit":25}

The status tool never loads the controller. If the module is available but has not discovered workers, request discovery once and poll status; the request returns immediately and does not start a test:

tests.request_automation_discovery {}
tests.get_automation_status {}

tests.inspect_automation_reports reads the controller's filtered report tree. It does not export files, clear history, or run a test. Use includeGroups:true only when you need hierarchy nodes as well as leaf reports. Empty state/result fields mean the controller has not received a result from a device; they do not mean success.

Use tests.get_automation_report {fullPath} after discovery for a single exact report. In an editor world, tests.get_functional_test_details {actor} returns current configuration and tests.audit_functional_tests {} reports disabled, running, undocumented, and unbounded tests without executing them.

Functional Tests are level actors. To add a small configured fixture to the current editor world, then inspect it:

tests.create_functional_test {
  "name":"FT_OpenDoor",
  "location":{"x":0,"y":0,"z":100},
  "description":"Door opens after the trigger is entered",
  "enabled":true,
  "setTimeLimit":true,
  "timeLimit":10
}
tests.list_functional_tests {"contains":"OpenDoor"}

Update only the fields that need changing. setDescription and setTimeLimit distinguish an intentional empty description or zero timeout from leaving those values alone:

tests.update_functional_test {
  "actor":"FT_OpenDoor",
  "enabled":true,
  "setDescription":true,
  "description":"Opens after one trigger entry",
  "setTimeLimit":true,
  "timeLimit":8
}

AFunctionalTest itself is an actor, not a standalone asset. Use bp.* to create a Functional Test Blueprint when its behaviour needs Blueprint events, and use level.*/asset.* for the map that contains it. Generic actor operations remain in actor.*.

Do not call test-execution tools from edit.self_test: automation and Functional Tests can require frames, maps, PIE, or worker messaging while the self-test holds the game thread. This kit deliberately provides no run, stop, clear, or export operation.

tests.get_functional_test_details {actor} inspects one Functional Test actor without running it, and tests.remove_functional_test {actor} deletes one from the editor level (refused while it runs). tests.request_automation_discovery and tests.get_automation_report need Automation Controller workers, so they are not part of the unattended self-test.

Tools

Legend. risk 0 = read-only, 1 = harmless editor op, 2 = modifies asset, 3 = deletes/replaces asset, 4 = project/config/build op, 5 = potentially destructive (calls above MaxAutoRisk need "_confirm": true). mutates = runs in a transaction (edit.undo reverts). requires PIE / requires world = refused without a PIE session / an open level. requires plugin = unavailable while the plugin is disabled. dryRun = honours the dryRun argument. smoke = covered by edit.self_test.

tests.audit_functional_tests (risk 0, requires world, smoke)

Audits loaded Functional Test actors without executing, stopping, or changing them.

Argument	Type	Description
contains	string	Case-insensitive substring of the actor label or object name.
includeDisabled	boolean	Include disabled Functional Test actors. Default true.
limit	integer	Default 100.

Returns: total, issues, message.

tests.create_functional_test (risk 2, mutates, requires world, smoke)

Adds a configured AFunctionalTest actor to the editor world; it does not execute the test.

Argument	Type	Description
name	string	required. Unique editor label for the new AFunctionalTest actor.
location	{x,y,z}	World location in centimetres.
description	string	Editable Functional Testing description.
enabled	boolean	Enable the actor for Functional Testing discovery. Default true.
setTimeLimit	boolean	Apply timeLimit; zero means no test timeout. Default false.
timeLimit	number	Default 0.0f.

Returns: test, message.

tests.get_automation_report (risk 0)

Finds one current Automation Controller report without starting, exporting, or clearing tests.

Argument	Type	Description
fullPath	string	required. Full report path reported by tests.inspect_automation_reports.

Returns: reports, total, message.

tests.get_automation_status (risk 0, smoke)

Returns the loaded Automation Controller state without starting tests or waiting for workers.

No arguments.

Returns: moduleLoaded, state, resultsAvailable, hasErrors, hasWarnings, hasLogs, deviceClusters, enabledTests, passes, reportOutputPath, message.

tests.get_functional_test_details (risk 0, requires world, smoke)

Returns one loaded Functional Test actor's configuration and last result without executing it.

Argument	Type	Description
actor	string	required. Functional Test actor label, object name, or object path.

Returns: test, message.

tests.inspect_automation_reports (risk 0, smoke)

Inspects the controller's current filtered report tree; it does not run, export, or clear tests.

Argument	Type	Description
contains	string	Case-insensitive substring of the report path or display name.
limit	integer	Maximum matching entries returned. Default 100.
includeGroups	boolean	Include group nodes as well as leaf test reports. Default false.

Returns: reports, total, message.

tests.list_functional_tests (risk 0, requires world, smoke)

Lists loaded AFunctionalTest actors in the editor world.

Argument	Type	Description
contains	string	Case-insensitive substring of the actor label or object name.
includeDisabled	boolean	Include disabled Functional Test actors. Default true.
limit	integer	Default 100.

Returns: tests, count, total, message.

tests.remove_functional_test (risk 3, mutates, destructive, requires world, smoke)

Deletes one Functional Test actor from the editor world; the test is not executed.

Argument	Type	Description
actor	string	required. Functional Test actor label, object name, or object path.

Returns: test, message.

tests.request_automation_discovery (risk 1)

Requests worker test discovery and returns immediately; call tests.get_automation_status to observe it.

No arguments.

Returns: moduleLoaded, state, resultsAvailable, hasErrors, hasWarnings, hasLogs, deviceClusters, enabledTests, passes, reportOutputPath, message.

tests.update_functional_test (risk 2, mutates, requires world, smoke)

Updates the enabled flag, description, or timeout of an existing AFunctionalTest actor.

Argument	Type	Description
actor	string	required. Actor label, object name, or object path.
enabled	boolean	Default true.
setDescription	boolean	Default false.
description	string
setTimeLimit	boolean	Default false.
timeLimit	number	Default 0.0f.

Returns: test, message.