M3.1 — UnrealSession, roles, instances

What you'll learn

• The three session classes — UnrealSession, UnrealSessionRole, UnrealSessionInstance — and the definition vs. live-instance distinction between them.
• Where UnrealAppConfig fits.
• How a test node uses these without micromanaging them.

How it applies (QA)

Multi-process bugs — a server that starts late, a client that launches with the wrong map, a role that never connects — are read and described in terms of these classes. Knowing which class owns "the plan" vs. "the running thing" lets you say precisely where a session went wrong.

Concepts

Definition vs. instance

The cleanest way to hold these three:

• UnrealSessionRole — the definition of one participant. "A client, on this device, with these arguments." A plan, not a process.
• UnrealSession — the definition of the whole arrangement. The set of roles plus how they relate. Still a plan: "two clients and a server, like so."
• UnrealSessionInstance — the live, running session. The actual processes that exist after UnrealSession is launched. This is the thing you monitor and tear down.

UnrealSession is the blueprint; UnrealSessionInstance is the building. You configure the former; you watch the latter.

UnrealAppConfig — how one process launches

A UnrealSessionRole needs to know how to start its process: which executable/build, what command line, what role type. UnrealAppConfig carries that "how to launch one Unreal app" recipe. One role → one app config → one launched process in the instance.

The lifecycle, in order

build UnrealSessionRole(s)         ← define each participant (type, device, args)
        │
        ▼
assemble a UnrealSession           ← the full arrangement (the plan)
        │
        ▼  launch
UnrealSessionInstance              ← live processes; monitor here
        │
        ▼  test ends / fails / times out
tear down the instance             ← Gauntlet kills all processes, collects artifacts

Your test rarely touches these directly

A UnrealTestNode (M4) configures what roles it wants through its UnrealTestConfiguration, and the base class does the work of building the UnrealSession, launching the UnrealSessionInstance, and tearing it down. You declare intent ("I need a server and two clients"); the framework operates the session machinery. You interact mostly to read the running instance's state and decide the verdict.

Pitfall: confusing 'configured' with 'running'

A role being present in the UnrealSession (the plan) does not mean its process came up in the UnrealSessionInstance (the reality). "The server is in the config but there's no server log" is exactly this gap — the plan had it; the launch didn't achieve it. Always confirm against the instance, not the definition.

Worked example

For "two clients play against a dedicated server," the objects are:

Object	Count	Role
UnrealSessionRole (server)	1	dedicated server participant
UnrealSessionRole (client)	2	client participants
UnrealAppConfig	3	one launch recipe per role
UnrealSession	1	the plan binding all three roles
UnrealSessionInstance	1	the live set of 3 processes once launched

When the test ends, the single UnrealSessionInstance is torn down — all three processes killed, all three roles' artifacts collected.

Exercise 1 — Plan or reality?

For each statement, say whether it describes the definition (UnrealSession/Role) or the live instance (UnrealSessionInstance):

1. "The session declares one server and four clients."
2. "Client 3's process exited with a crash."
3. "Each client role passes -game and a map override."
4. "Only three of the four client processes are actually alive."

Exercise 2 — Count the objects

A test needs one editor host, one dedicated server, and three clients. How many UnrealSessionRoles, UnrealAppConfigs, UnrealSessions, and UnrealSessionInstances exist for one run?

Self-check — answers

Exercise 1: 1 definition, 2 instance, 3 definition, 4 instance.

Exercise 2: 5 UnrealSessionRoles (1 editor + 1 server + 3 clients), 5 UnrealAppConfigs (one launch recipe each), 1 UnrealSession (the single plan), 1 UnrealSessionInstance (the single live run). The rule: one role and one app config per process; one session and one instance per run.

Done when

• [ ] You can state the definition-vs-instance distinction across the three classes.
• [ ] You can place UnrealAppConfig (one launch recipe per role).
• [ ] You can walk the session lifecycle from roles to instance teardown.
• [ ] You can explain why "in the config" ≠ "running," and where to confirm.

---

Next: M3.2 — Roles in practice.