---
layout: default
title: System Examples
---
# The System actor
The `System` actor provides access to built-in functionalities that don't fall into other categories like `Terminal` or
`Web`. These are useful for debugging, controlling test flow, generating dynamic data, and verifying system state like
services and ports.
## Declaring the Actor
To use system actions, you must declare the `System` actor in your `actors` block.
```choreo
actors {
System
Terminal
}
```
## Actions
### `log`
Prints a message to the console during the test run. This is extremely useful for debugging test logic and inspecting
variable values.
**Syntax:** `System log "<message>"`
#### Example:
```choreo
when:
System log "Starting the user creation flow."
System log "The user ID is ${userId}"
```
### `pause`
Pauses the test execution for a specified duration. This can be helpful when waiting for an asynchronous process that
has no other clear signal for completion. Durations can be specified in seconds (s) or milliseconds (ms).
**Syntax:** `System pause <duration>`
#### Example:
```choreo
when:
Terminal run "start-background-process.sh"
# Give the process a moment to initialise
System pause 2s
```
### `uuid`
Generates a version 4 UUID and stores it in a variable. This is perfect for creating unique identifiers for resources,
flow IDs, or any other data that needs to be unique for each test run.
**Syntax:** `System uuid as <variable_name>`
#### Example:
```choreo
when:
System uuid as NEW_USER_ID
Terminal run "create-user --id ${NEW_USER_ID}"
```
### `timestamp`
Gets the current Unix timestamp (as a string) and stores it in a variable.
**Syntax:** `System timestamp as <variable_name>`
#### Example:
```choreo
when:
System timestamp as REQUEST_TIME
Web set_header "X-Request-Time" "${REQUEST_TIME}"
```
## Conditions
The `System` actor also provides conditions for checking system state. These are useful for verifying that required
services are running or that ports are available before running tests.
> **Cross-Platform Support:** All system conditions work on **Windows**, **macOS**, and **Linux**. The underlying
> implementation uses the `sysinfo` crate for process enumeration and the `which` crate for executable lookup, providing
> consistent behavior across all major operating systems.
### Service Conditions
#### `service_is_running`
Checks if a service or process is currently running on the system. This uses cross-platform process enumeration to find
matching processes by name.
- On **Windows**, it matches process names with or without the `.exe` extension
- On **macOS** and **Linux**, it matches process names directly
**Syntax:** `System service_is_running "<service_name>"`
#### `service_is_stopped`
Checks if a service or process is not currently running.
**Syntax:** `System service_is_stopped "<service_name>"`
#### `service_is_installed`
Checks if a service or executable is installed on the system (regardless of whether it's running). This performs
a cross-platform PATH lookup first, then falls back to platform-specific service definition checks:
- On **Windows**, checks Windows services via `sc query`
- On **macOS**, checks launchd plist files in standard locations
- On **Linux**, checks systemd unit files and init.d scripts
**Syntax:** `System service_is_installed "<service_name>"`
#### Example:
```choreo
test DatabaseReady "Ensure database is ready before tests" {
given:
Test can_start
when:
Terminal run "echo 'Checking database...'"
then:
Terminal last_command succeeded
System service_is_running "postgresql"
}
```
### Port Conditions
Port conditions work cross-platform by attempting to bind to the port. If binding fails with "address already in use",
it means something is listening on that port. For privileged ports or special cases, platform-specific fallback commands
are used (`lsof` on macOS, `ss` on Linux, `netstat` on Windows).
#### `port_is_listening`
Checks if something is listening on the specified port. This is useful for verifying that a server has started.
**Syntax:** `System port_is_listening <port_number>`
#### `port_is_closed`
Checks if a port is available (nothing is listening on it). This is useful for ensuring a port is free before starting
a service.
**Syntax:** `System port_is_closed <port_number>`
#### Example:
```choreo
test ServerStarted "Verify the server is listening" {
given:
Test can_start
when:
Terminal run "start-server.sh &"
System pause 2s
then:
System port_is_listening 8080
}
test PortAvailable "Ensure port is free before starting" {
given:
Test can_start
when:
Terminal run "echo 'Checking port availability'"
then:
Terminal last_command succeeded
System port_is_closed 3000
}
```
## Full Example
This example demonstrates using System conditions to verify environment readiness:
```choreo
feature "System Conditions Demo"
actors: System, Terminal
scenario "Verify system environment" {
test CheckPorts "Verify required ports are available" {
given:
Test can_start
when:
Terminal run "echo 'Checking port availability'"
then:
Terminal last_command succeeded
System port_is_closed 8080
System port_is_closed 5432
}
test CheckServices "Verify required services" {
given:
Test has_succeeded CheckPorts
when:
Terminal run "echo 'Checking services'"
then:
Terminal last_command succeeded
System service_is_installed "docker"
}
}
```
See the example file
[examples/system_conditions.chor](https://github.com/cladam/choreo/blob/main/examples/system_conditions.chor) for a
runnable demonstration of these conditions.