From ab5305d8c6257e2d02e42da6cc1ca916629415aa Mon Sep 17 00:00:00 2001 From: opieter-aws Date: Thu, 25 Jun 2026 13:36:38 -0400 Subject: [PATCH] docs: improve testing instructions --- strands-py/docs/TESTING.md | 1 + strands-ts/docs/TESTING.md | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/strands-py/docs/TESTING.md b/strands-py/docs/TESTING.md index 2edc257434..bebd1217dc 100644 --- a/strands-py/docs/TESTING.md +++ b/strands-py/docs/TESTING.md @@ -70,6 +70,7 @@ assert tru_message == exp_message ## Test Organization +- **Prefer adding assertions to an existing test over writing a new one.** When a test already sets up the same scenario, extend it with the new assertions rather than duplicating the arrange step in a new test function. Add a separate test only for a distinct behavior, execution path, or error condition. - **Name tests `test__`.** The test module already names the subject, so the class/subject should be omitted: `test__init__default_model_id`, `test_update_config_validation_warns_on_unknown_keys`. Add a subject prefix (`test___`) **only** when one module covers several subjects and the bare method name would be ambiguous. - **Default to flat, module-level functions.** Most of the suite is flat. - **Use a `class Test` only when tests share class-scoped setup or fixtures** — not merely to group related cases (a module already groups them). Inside a class, the method name can drop the redundant subject since the class supplies it. diff --git a/strands-ts/docs/TESTING.md b/strands-ts/docs/TESTING.md index c944272601..ca937c24cd 100644 --- a/strands-ts/docs/TESTING.md +++ b/strands-ts/docs/TESTING.md @@ -164,9 +164,9 @@ describe('calculateTotal', () => { ## Test Batching Strategy -**Rule**: When test setup cost exceeds test logic cost, you MUST batch related assertions into a single test. +**Rule**: When test setup cost exceeds test logic cost, you MUST batch related assertions into a single test. Prefer extending an existing test over adding a new one. If a test already arranges the scenario your new behavior needs, add the assertion(s) there rather than duplicating the setup. Reach for a new test only for the cases listed under "You SHOULD keep separate tests for" below. -**You MUST batch when**: +**You MUST batch (or extend an existing test) when**: - Setup complexity > test logic complexity - Multiple assertions verify the same object state