Skip to content

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 accounts_under_test in cats.yaml.

required

Raises:

Type Description
CatsConfigError

name is not an account keyname in the loaded cats.yaml, or cats.yaml leaves aws_region unset with no AWS_REGION in the environment.

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: host is a URL or not a hostname/IP literal, or port is 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 default http_call/https_call/tcp_call/udp_call raise whichever their dispatched transport raises.
  • botocore.exceptions.ClientError is passed through unwrapped when an AWS API refuses the underlying call for a reason CATS does not model (an AccessDenied on lambda:Invoke or ssm:SendCommand, for example). The one exception is the Lambda execution-role propagation race: a lambda:Invoke AccessDeniedException whose 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 sent is not a UDP result, or the datagram never left the host (response is not SENT). A DNS_FAILURE is not "dropped in flight", so it must not be allowed to read as False.

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.