<commit_before><!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
-->

# Goals

This document aims to develop and maintain consistency across the system tests in
the Amazon provider package and sets forth guidelines to use when possible.  With
the expectation that there will always be some edge cases, please refer to this
document as a guide when contributing system tests for the Amazon provider package.

Contributions are welcome and are greatly appreciated! Every bit helps, and credit
will always be given.  For example, I stole that line from @potiuk!

# Scope

This guide is meant to be used in addition to the [community system test design
guide](/tests/system/README.md) and only applies to system tests within the Amazon
provider package, though other providers are welcome to adopt them as well.  In any
cases of conflicting information or confusion, this document should take precedence
within the Amazon provider package.

# Tenants

* Keep it Self-Contained
* Keep it DAMP
* Use the Helpers

## Keep it Self-Contained

For system tests, we would prefer to see each test be a fully self-contained unit.
This means that any infrastructure which is needed, such as an S3 bucket, must be
created and destroyed in the test's setup and teardown steps.  Some exceptions are
outlined below in the `SystemTestContextBuilder()` section.  Please document all
prerequisites for a given system test in your code for easy replication.

## Keep it DAMP

Whenever possible, avoid adding new helper methods to reuse configuration or setup
code.  This means there will be duplicate code across tests, which violates the DRY
(Don't Repeat Yourself) programming principle, but ensures that any given test can
be modified easily without having to consider what those changes may mean for every
other test.

Similarly, whenever possible, a variable should be defined in the module instead of
checking for it in external locations.  For example, if you create and break down an
S3 bucket, the bucket name should be defined in the file rather than setting it with
an environment variable.

## Use the Helpers

Some helper methods for system tests have been provided in the [utils module](aws/utils/__init__.py).

### SystemTestContextBuilder()

`SystemTestContextBuilder()` should be used as the first task in every Amazon system
test.  When used without any stub methods, it will generate and set the test's `ENV_ID`.
It will check for an environment variable defining the system test environment ID.  If
one is found, it will validate that the ID meets system test requirements.  Otherwise,
it will generate one and export a value.  For more information, see `ENV_ID` below.

Any variables which need to be fetched from an external source, such as an environment
variable or SSM, should be added with the `.add_variable()` stub method.  The method
will check a number of sources to find a value before falling back to the default.
Use this to provide values for things which must be generated before the test can run.
Whenever possible, it is preferred to use default values when creating these resources
and document the settings in the code for easy reproduction.  For example, a comment
such as "This test requires the ARN of a default EC2 instance named `system_test_instance`."
is preferred over creating an EC2 instance using custom settings to try to improve<commit_msg>Add "Clean" to the Amazon System Test Contrib Guide (#26811)<commit_after><!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
-->

# Goals

This document aims to develop and maintain consistency across the system tests in
the Amazon provider package and sets forth guidelines to use when possible.  With
the expectation that there will always be some edge cases, please refer to this
document as a guide when contributing system tests for the Amazon provider package.

Contributions are welcome and are greatly appreciated! Every bit helps, and credit
will always be given.  For example, I stole that line from @potiuk!

# Scope

This guide is meant to be used in addition to the [community system test design
guide](/tests/system/README.md) and only applies to system tests within the Amazon
provider package, though other providers are welcome to adopt them as well.  In any
cases of conflicting information or confusion, this document should take precedence
within the Amazon provider package.

# Tenants

* Keep it Self-Contained
* Keep it DAMP
* Keep it Clean
* Use the Helpers

## Keep it Self-Contained

For system tests, we would prefer to see each test be a fully self-contained unit.
This means that any infrastructure which is needed, such as an S3 bucket, must be
created and destroyed in the test's setup and teardown steps.  Some exceptions are
outlined below in the `SystemTestContextBuilder()` section.  Please document all
prerequisites for a given system test in your code for easy replication.

## Keep it DAMP

Whenever possible, avoid adding new helper methods to reuse configuration or setup
code.  This means there will be duplicate code across tests, which violates the DRY
(Don't Repeat Yourself) programming principle, but ensures that any given test can
be modified easily without having to consider what those changes may mean for every
other test.

Similarly, whenever possible, a variable should be defined in the module instead of
checking for it in external locations.  For example, if you create and break down an
S3 bucket, the bucket name should be defined in the file rather than setting it with
an environment variable.

## Keep it Clean

Code snippets in the system tests are embedded in the [documentation pages](
https://airflow.apache.org/docs/apache-airflow-providers-amazon/stable/operators/index.html).
In order to minimize confusion for new users looking at those doc pages, the code
snippets should be concise and not include parameters which are not needed for the
Operator to function.  Any parameters which are not needed for the Operator but are
needed for the system test (`wait_for_completion` or `trigger_rule` as two examples)
should be added outside the snippet.  For example:

```
# [START howto_operator_cloudformation_delete_stack]
delete_stack = CloudFormationDeleteStackOperator(
    task_id='delete_stack',
    stack_name=cloudformation_stack_name,
)
# [END howto_operator_cloudformation_delete_stack]
delete_stack.trigger_rule = TriggerRule.ALL_DONE
```

## Use the Helpers

Some helper methods for system tests have been provided in the [utils module](aws/utils/__init__.py).

### SystemTestContextBuilder()

`SystemTestContextBuilder()` should be used as the first task in every Amazon system
test.  When used without any stub methods, it will generate and set the test's `ENV_ID`.
It will check for an environment variable defining the system test environment ID.  If
one is found, it will validate that the ID meets system test requirements.  Otherwise,
it will generate one and export a value.  For more information, see `ENV_ID` below.

Any variables which need to be fetched from an external source, such as an environment
variable or SSM, should be added with the `.add_variable()` stub method.  The method
will check a number of sources to find a value before falling back to the default.
Use this to provide values for things which must be generated before the test can run.
Whenever possible, it is preferred to use default values when creating these resources
and document the settings in the code for easy reproduction.  For example, a comment
such as "This test requires the ARN of a default EC2 instance named `system_test_instance`."
is preferred over creating an EC2 instance using custom settings to try to improve
{'fraction_non_alphanumeric': 0.03962678375411636, 'fraction_numerical': 0.002305159165751921, 'mean_word_length': 4.586143470263642, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 1, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7478358', 'n_tokens_mistral': 2166, 'n_tokens_neox': 2097, 'n_words': 1357}