feat!: job/step/task API functions and session log assertions

What was the problem/requirement? (What/Why)

There were no high-level APIs for asserting about contents in the CloudWatch session logs uploaded by the worker agent.

What was the solution? (How)

To better model the AWS Deadline Cloud resource model and APIs, I added classes and functions that allow developers to traverse from Job → Step → Task → Session which enables test cases using jobs with multiple steps and tasks. The Session class provides a get_session_log() method for the common use-case of collecting the session log events into memory for use in a test.

Further, the Session class has an even higher-level method (Session.assert_log_contains(...)) for asserting that a Python regular expression pattern is found in the concatenated session log in CloudWatch. In addition, this method employs exponential back-off to help account for the eventually-consistent property of logs becoming available in CloudWatch.

The exponential backoff multiplier can be configured (defaults to 300ms) and the number of backoff/retries can also be configured (default to 4). The total back-off is 4.5s using the defaults.

Another common use-case is submitting a job that has a single step and task and looking for a pattern in the task's session log. For this, a new Job.assert_single_task_log_contains(...) method was added.

What is the impact of this change?

Consumers of deadline-cloud-test-fixtures now have high-level APIs for traversing from a job through steps, tasks, and sessions, and session logs. Consumer have high-level APIs for common test use-cases to assert that a regex pattern exists in the session logs.

How was this change tested?

Unit Tests

Added unit tests for the new functionality

E2E Tests

Installed the modified deadline-cloud-test-fixtures into a deadline-cloud-worker-agent checkout dev env

Ran existing Linux and Windows E2E tests and confirmed they still pass

Modified this existing Linux job submission E2E test code to use the new Job.assert_single_task_log_contains(...) which makes downstream calls to all of the newly added APIs. The changed code was:

job.assert_single_task_log_contains(
    deadline_client=deadline_client,
    logs_client=boto3.client(
        "logs",
        config=botocore.config.Config(retries={"max_attempts": 10, "mode": "adaptive"}),
    ),
    expected_pattern=rf'I am: {job_run_as_user.user}',
)

The test passed successfully.

Was this change documented?

Is this a breaking change?

Yes:

in PR feedback iterations, we decided to change the existing Job.lifecycle_status attribute from a str → JobLifecycleStatus enum (see https://github.com/aws-deadline/deadline-cloud-test-fixtures/pull/150#discussion_r1745823449)
It was discovered there was a TaskStatus.UNKNOWN enum value that is not part of the AWS Deadline Cloud API so it was removed (see ref docs)

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

aws-deadline / deadline-cloud-test-fixtures