CATS AccountUnderTest
The objects a test interacts with: the account fixture and its network handlers.
Session plumbing and probe internals are not part of the public API. Network targets are
reached as attributes (account.<target>), described in
writing tests.
AccountUnderTest
A class to encapsulate a child test account relationship to the parent test runner.
These are consumed in tests with Account fixtures provided by the CATS pytest plugin.
Constructing one assumes the account's default test role and reads its CATS stack, so
the deployed infrastructure must exist. Network targets declared in cats.yaml are
reached as attributes: account.<target_name> returns a NetworkHandler. The
single-word public attributes are exactly name, partition, session, role
and tags; every other public attribute contains an underscore, which a target name
cannot, so a valid target name never shadows an attribute.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The account's keyname under |
required |
Raises:
| Type | Description |
|---|---|
CatsConfigError
|
|
CatsInfrastructureError
|
The account's CATS stack is missing, its outputs do not match the configured network targets, or the default test role cannot be assumed (no credentials in the environment, an unreachable endpoint, an STS refusal). |
CatsVersionMismatchError
|
The stack was deployed by another CATS release. |
available_network_targets
property
Network target names available for this account.
network_handlers
property
Return all network handlers for this account.
role
property
Allows access to additional defined roles in cats.yaml by defined attribute name
Returns:
| Name | Type | Description |
|---|---|---|
SessionHandler |
SessionHandler
|
A class that creates an AWS session based on attribute name defined in cats.yaml |
session
property
Returns the default CATS testing session: the account's default test role, assumed once and shared by every probe and client on this account. Its credentials refresh themselves, so a session held for a whole test run stays valid.
Convenience method for AccountUnderTest.role.default
Returns:
| Type | Description |
|---|---|
Session
|
boto3.Session instantiation |
tags
property
Tags defined for this account in config.
udp_receipt_token
property
Token this account's UDP listeners require as a '{token}:' message prefix.
udp_call prepends it automatically; it is exposed for power users crafting raw traffic (e.g. via shell()). None for stacks deployed before UDP receipt tokening.
get_network_handler_by_tag(tag_name, tag_value=None)
Get exactly one network handler matching a tag, or raise.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tag_name
|
str
|
Tag key to filter by |
required |
tag_value
|
str | None
|
Optional tag value to match. If None, matches any value (tag presence only). |
None
|
Raises:
| Type | Description |
|---|---|
CatsUsageError
|
If zero or multiple handlers match |
network_handlers_by_tag(tag_name, tag_value=None)
Iterate over network handlers that have a specific tag.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tag_name
|
str
|
Tag key to filter by |
required |
tag_value
|
str | None
|
Optional tag value to match. If None, matches any value (tag presence only). |
None
|
NetworkHandler
Allows AccountUnderTest to target network segments in cats.yaml by using a class property, by implementing a custom attribute lookup.
For example: result = AccountUnderTest.subnet_a.http_call("google.com", 443)
Every network call returns a CatsNetworkResult. Compare it to a CatsNetworkResponse member: SUCCESS, REFUSED, TIMEOUT, DNS_FAILURE, TLS_FAILURE, FAILURE, or SENT (UDP). The result's reason, http_status, and correlation_id are diagnostics carried alongside the category.
A NetworkHandler is constructed by AccountUnderTest when a network target attribute is
read; __init__ is internal and not part of the compatibility contract. The public
surface is name, tags, ec2_dns_name, response_bucket_name and the call
methods.
What every *_call can raise, on top of what its own docstring lists:
CatsUsageError:hostis a URL or not a hostname/IP literal, orportis out of range. Checked before any AWS call.CatsConfigError: the handler the method names (ec2_*,lambda_*) is not deployed for this target. Checked before any AWS call.CatsSSMError(EC2 transport) /CatsLambdaInvocationError(Lambda transport): the transport failed or the probe itself errored, so no result category can be honestly returned. The defaulthttp_call/https_call/tcp_call/udp_callraise whichever their dispatched transport raises.botocore.exceptions.ClientErroris passed through unwrapped when an AWS API refuses the underlying call for a reason CATS does not model (anAccessDeniedonlambda:Invokeorssm:SendCommand, for example). The one exception is the Lambda execution-role propagation race: alambda:InvokeAccessDeniedExceptionwhose message is "...cannot be assumed by Lambda" is retried for a bounded window before it is allowed to propagate.
ec2_dns_name
property
The DNS name for deployed EC2 listener in this network target
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
DNS name |
response_bucket_name
property
The S3 bucket name for deployed S3 bucket in this account for receiving UDP call side-effects.
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
S3 bucket name |
ec2_http_call(host, port)
Make an HTTP call (GET /) from the EC2 instance via SSM RunCommand.
The probe asks whether the path is open and something answers HTTP, not what the application does with a request: any status in reply is SUCCESS.
Returns:
| Name | Type | Description |
|---|---|---|
CatsNetworkResult |
CatsNetworkResult
|
SUCCESS if any HTTP status arrived (http_status carries the code; redirects are not followed), REFUSED if the connection was refused or reset, TIMEOUT if the TCP connect got no answer (consistent with a silent drop), DNS_FAILURE if the name did not resolve, FAILURE for anything else, including a backend that accepted the connection and never replied (reason starts "connected; no HTTP reply"). |
Raises:
| Type | Description |
|---|---|
CatsSSMError
|
If SSM command fails due to infrastructure problems |
ec2_https_call(host, port)
Make an HTTPS call (GET /) from the EC2 instance via SSM RunCommand.
Returns:
| Name | Type | Description |
|---|---|---|
CatsNetworkResult |
CatsNetworkResult
|
SUCCESS if any HTTP status arrived (http_status carries the code), REFUSED, TIMEOUT, DNS_FAILURE, TLS_FAILURE if TCP connected but the handshake failed (untrusted CA, plaintext listener, ...), FAILURE for anything else; see ec2_http_call for what each proves. |
Raises:
| Type | Description |
|---|---|
CatsSSMError
|
If SSM command fails due to infrastructure problems |
ec2_tcp_call(host, port)
Make a TCP connection from the EC2 instance via SSM RunCommand.
Returns:
| Name | Type | Description |
|---|---|---|
CatsNetworkResult |
CatsNetworkResult
|
SUCCESS if the TCP connection succeeded, REFUSED if the connection was refused or reset, TIMEOUT if no response arrived before the timeout (consistent with a silent drop), DNS_FAILURE if the name did not resolve, FAILURE for unclassified errors. |
Raises:
| Type | Description |
|---|---|
CatsSSMError
|
If SSM command fails due to infrastructure problems |
ec2_udp_call(host, port)
Send a UDP datagram from the EC2 instance via SSM RunCommand. Pass the result to receive_s3 on the receiving account to confirm arrival.
Returns:
| Name | Type | Description |
|---|---|---|
CatsNetworkResult |
CatsNetworkResult
|
SENT, DNS_FAILURE, or FAILURE, with correlation_id set to the generated receipt ID. REFUSED and TIMEOUT are unreachable for UDP: the probe sends on an unconnected socket, so the datagram leaving the host is all it can observe. |
Raises:
| Type | Description |
|---|---|
CatsSSMError
|
If SSM command fails due to infrastructure problems |
http_call(host, port)
Make an HTTP call (GET /) using the first enabled network handler; outcomes and errors are those of ec2_http_call or lambda_http_call.
https_call(host, port)
Make an HTTPS call (GET /) using the first enabled network handler; outcomes and errors follow ec2_https_call or lambda_https_call.
lambda_http_call(host, port)
Make an HTTP call (GET /) using Lambda deployed in this target network segment. Requires 'lambda' in enabled_network_handlers.
Returns:
| Name | Type | Description |
|---|---|---|
CatsNetworkResult |
CatsNetworkResult
|
SUCCESS (any HTTP status in reply; http_status carries the code), REFUSED, TIMEOUT, DNS_FAILURE, or FAILURE - see ec2_http_call for what each proves. |
Raises:
| Type | Description |
|---|---|
CatsConfigError
|
If Lambda handler not enabled |
CatsLambdaInvocationError
|
If the Lambda invocation or the probe itself fails |
lambda_https_call(host, port)
Make an HTTPS call (GET /) using Lambda deployed in this target network segment. Requires 'lambda' in enabled_network_handlers.
Returns:
| Name | Type | Description |
|---|---|---|
CatsNetworkResult |
CatsNetworkResult
|
SUCCESS (any HTTP status in reply; http_status carries the code), REFUSED, TIMEOUT, DNS_FAILURE, TLS_FAILURE, or FAILURE - see ec2_https_call for what each proves. |
Raises:
| Type | Description |
|---|---|
CatsConfigError
|
If Lambda handler not enabled |
CatsLambdaInvocationError
|
If the Lambda invocation or the probe itself fails |
lambda_tcp_call(host, port)
Make a TCP connection using Lambda deployed in this target network segment. Requires 'lambda' in enabled_network_handlers.
Returns:
| Name | Type | Description |
|---|---|---|
CatsNetworkResult |
CatsNetworkResult
|
SUCCESS, REFUSED, TIMEOUT, DNS_FAILURE, or FAILURE - see CatsNetworkResponse docs. |
Raises:
| Type | Description |
|---|---|
CatsConfigError
|
If Lambda handler not enabled |
CatsLambdaInvocationError
|
If the Lambda invocation or the probe itself fails |
lambda_udp_call(host, port)
Send a UDP datagram using Lambda deployed in this target network segment. Pass the result to receive_s3 on the receiving account to confirm arrival. Requires 'lambda' in enabled_network_handlers.
Returns:
| Name | Type | Description |
|---|---|---|
CatsNetworkResult |
CatsNetworkResult
|
SENT, DNS_FAILURE, or FAILURE, with correlation_id set to the generated receipt ID. REFUSED and TIMEOUT are unreachable for UDP. |
Raises:
| Type | Description |
|---|---|
CatsConfigError
|
If Lambda handler not enabled |
CatsLambdaInvocationError
|
If the Lambda invocation or the probe itself fails |
receive_s3(sent, *, timeout=10.0, interval=2.0)
Confirm that a UDP datagram sent with udp_call arrived at a CATS listener, by polling this account's response bucket for the receipt the listener writes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sent
|
CatsNetworkResult
|
The result returned by udp_call / ec2_udp_call / lambda_udp_call |
required |
timeout
|
float
|
Maximum seconds to wait for the receipt (default 10.0); keyword-only |
10.0
|
interval
|
float
|
Seconds between polls (default 2.0); keyword-only |
2.0
|
Returns:
| Name | Type | Description |
|---|---|---|
bool |
bool
|
True if the receipt exists, False if it did not appear within timeout |
Raises:
| Type | Description |
|---|---|
CatsUsageError
|
If |
CatsInfrastructureError
|
The response bucket cannot be read (missing bucket, access denied): a receipt that cannot be checked must not read as False. |
shell(command)
Run a shell command on the EC2 instance via SSM AWS-RunShellScript.
Requires allow_shell: true on the account's account_settings at deploy time.
EC2-only — does not participate in handler dispatch. Runs as root with the
EC2 instance's IAM role (a hand-scoped SSM Agent policy with no Parameter
Store read, plus s3:PutObject on the response bucket), not the CATS test
role. The check is a convenience; the real enforcement is the test role's
IAM policy, set at deploy time.
Shell metacharacters (pipes, redirects, &&) work within a single command string. When passing a list, each element is an independent line — not a pipeline.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
command
|
str | list[str]
|
Shell command string, or list of command lines. |
required |
Returns:
| Type | Description |
|---|---|
ShellResult
|
ShellResult with stdout, stderr, exit_code, duration_ms, stdout_truncated, stderr_truncated. |
ShellResult
|
stdout and stderr are stripped of trailing whitespace; truncation flags are computed |
ShellResult
|
against the raw SSM output before stripping. |
Raises:
| Type | Description |
|---|---|
CatsConfigError
|
If allow_shell is not enabled for this account. |
CatsSSMError
|
If SSM infrastructure fails (instance unreachable, timeout, etc.). |
tcp_call(host, port)
Make TCP call using the first enabled network handler; outcomes and errors are those of ec2_tcp_call or lambda_tcp_call.
udp_call(host, port)
Send a UDP datagram using the first enabled network handler; outcomes and errors are those of ec2_udp_call or lambda_udp_call.