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

[jusiskin]

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

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

2. 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?

No

Is this a breaking change?

Yes:

1. in PR feedback iterations, we decided to change the existing Job.lifecycle_status attribute from a str → JobLifecycleStatus enum (see feat!: job/step/task API functions and session log assertions #150 (comment))
2. 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-Samuel]

Should we change this to use the JobLifecycleStatus enum?

[jusiskin]

Discussed offline and the one concern is that this PR becomes a breaking change. We decided that this was an overall improvement valuable enough to justify the breaking change. Rationale:

1. Using an enum will help test authors with IDEs that support type hints and code completion. Supporting IDEs will suggest the possible values for the enum making it easier to write tests.
2. We are pre-1.0 and we believe that there are very few consumers of this package — likely only consumed by AWS Deadline Cloud repositories.

I've switched to the enum and marked the commit as a breaking change

[AWS-Samuel]

Typo: UDATE_FAILED -> UPDATE_FAILED

Likewise, should we change this to use StepLifecycleStatus?

[jusiskin]

Switched to StepLifecycleStatus

[sonarcloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud