microsoft-agents-testing quality of life improvements and doc updates

[Rodrigo Brandão (rodrigobr-msft)]

This pull request significantly improves the documentation for the microsoft-agents-testing package by clarifying the fluent assertion APIs, introducing new guides, and enhancing the CLI and utility documentation. The changes make it much easier to understand and use the assertion framework, the CLI, and advanced matching features. The most important updates are grouped below.

Assertion API and Usage Documentation Improvements:

• Added a comprehensive new guide, ASSERTIONS.md, covering the Expect and Select assertion engine, typed wrappers (ActivityExpect, ExchangeExpect, etc.), matching rules, lambda conventions, and diagnostic output.
• Updated README.md and API.md to clarify the differences between expect()/select() (now returning ActivityExpect/ActivitySelect) and ex_expect()/ex_select() (now returning ExchangeExpect/ExchangeSelect). Updated API reference tables and docstrings accordingly. [1] [2] [3] [4] [5] [6]
• Improved documentation for lambda predicates, specifying that lambda parameters should be named x, actual, or value to receive the resolved value during evaluation. [1] [2]

Advanced Matching and Utility Functions:

• Documented the contains utility for matching nested values in models, dicts, or iterables, with usage examples and explanation of valid invocation patterns. Added cross-references to UTILITIES.md. [1] [2] [3]

CLI Documentation:

• Added a new CLI.md guide detailing the agt command, global options, scenario commands (chat, post, load, run), environment commands, and scaffolding.
• Clarified CLI option names in API.md (e.g., changed --json-file to --json_file).

Transcript Formatting Documentation:

• Updated transcript formatter documentation to distinguish between ConversationTranscriptFormatter, ActivityTranscriptFormatter, and JsonTranscriptFormatter, and clarified their outputs.

Documentation Organization:

• Updated all documentation index tables to reference new and reorganized guides under the docs/ directory, including ASSERTIONS.md, CLI.md, and UTILITIES.md. [1] [2]

These changes greatly improve the discoverability and clarity of the testing package’s features and should make it much easier for new and existing users to write robust agent tests.

[Copilot]

Pull request overview

This pull request enhances the microsoft-agents-testing package’s usability by adding new fluent-testing utilities and typed wrappers, expanding predicate/lambda support, and substantially reorganizing/expanding documentation and runnable samples to clarify how to use the assertion engine and CLI.

Changes:

• Added contains / Contains nested traversal predicate helper plus tests and utility docs.
• Introduced typed fluent wrappers (ActivityExpect/Select, ExchangeExpect/Select) and updated AgentClient shortcuts/tests accordingly.
• Improved fluent predicate evaluation (lambda arg name support for value, truthiness handling) and added/updated extensive docs and samples.

Reviewed changes

Copilot reviewed 36 out of 36 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
dev/microsoft-agents-testing/tests/utils/test_pred.py	Adds coverage for the new contains/Contains nested predicate helper.
dev/microsoft-agents-testing/tests/core/test_type_defs.py	Tests typed wrappers for activities and exchanges.
dev/microsoft-agents-testing/tests/core/test_agent_client.py	Updates/extends tests to assert typed expect/select return types.
dev/microsoft-agents-testing/tests/core/fluent/test_select.py	Adds tests for value-named lambda args and root callable truthiness in Select.where().
dev/microsoft-agents-testing/tests/core/fluent/test_expect.py	Adds tests for value-named lambda args in Expect.that().
dev/microsoft-agents-testing/tests/core/fluent/backend/test_transform.py	Adds a test to validate _invoke supports a value parameter name.
dev/microsoft-agents-testing/tests/core/fluent/backend/test_model_predicate.py	Adds coverage for truthiness behavior when root callables return empty lists.
dev/microsoft-agents-testing/README.md	Updates top-level package readme with typed shortcut notes, contains, and doc index changes.
dev/microsoft-agents-testing/microsoft_agents/testing/utils/contains.py	Implements Contains predicate and the contains() factory.
dev/microsoft-agents-testing/microsoft_agents/testing/utils/init.py	Exposes contains from microsoft_agents.testing.utils.
dev/microsoft-agents-testing/microsoft_agents/testing/core/type_defs.py	Introduces typed Expect/Select wrappers for Activity and Exchange.
dev/microsoft-agents-testing/microsoft_agents/testing/core/fluent/select.py	Refactors to SelectBase + concrete Select, with generic/self-typed chaining updates.
dev/microsoft-agents-testing/microsoft_agents/testing/core/fluent/expect.py	Refactors to ExpectBase + concrete Expect for typed wrapper reuse.
dev/microsoft-agents-testing/microsoft_agents/testing/core/fluent/backend/types/unset.py	Renames internal Unset class to _Unset while keeping the singleton Unset.
dev/microsoft-agents-testing/microsoft_agents/testing/core/fluent/backend/transform.py	Extends predicate invocation to support value parameter name; broadens eval typing.
dev/microsoft-agents-testing/microsoft_agents/testing/core/fluent/backend/model_predicate.py	Updates match truthiness computation and broadens accepted input types.
dev/microsoft-agents-testing/microsoft_agents/testing/core/fluent/init.py	Exports ExpectBase/SelectBase alongside Expect/Select.
dev/microsoft-agents-testing/microsoft_agents/testing/core/agent_client.py	Updates AgentClient fluent shortcuts to return typed wrappers.
dev/microsoft-agents-testing/microsoft_agents/testing/core/init.py	Re-exports new typed wrappers and base classes from core.
dev/microsoft-agents-testing/microsoft_agents/testing/init.py	Re-exports new typed wrappers and base classes from the top-level package.
dev/microsoft-agents-testing/docs/UTILITIES.md	Adds a new utilities guide documenting contains, poll, send, and ex_send.
dev/microsoft-agents-testing/docs/samples/utilities.py	Adds a runnable sample demonstrating contains, poll, send, and ex_send.
dev/microsoft-agents-testing/docs/samples/transcript_formatting.py	Updates sample to reflect new transcript formatters and convenience functions.
dev/microsoft-agents-testing/docs/samples/test_motivation_assertions.py	Normalizes punctuation in the MOTIVATION assertion sample strings.
dev/microsoft-agents-testing/docs/samples/scenario_registry_demo.py	Updates sample docstring/comment formatting and wording.
dev/microsoft-agents-testing/docs/samples/quickstart.py	Updates sample docstring/comment formatting and wording.
dev/microsoft-agents-testing/docs/samples/pytest_plugin_usage.py	Updates sample docs and demonstrates typed expect/select usage.
dev/microsoft-agents-testing/docs/samples/multi_client.py	Updates sample output/formatter usage and docstring/comment formatting.
dev/microsoft-agents-testing/docs/samples/interactive.py	Updates sample to use format() output and refreshed documentation text.
dev/microsoft-agents-testing/docs/samples/deep_dive_assertions.py	Adds a new deep-dive sample walking through assertions, wrappers, and contains.
dev/microsoft-agents-testing/docs/samples/init.py	Updates sample index text and includes new samples.
dev/microsoft-agents-testing/docs/SAMPLES.md	Updates runnable samples guide, including module-run commands and new samples.
dev/microsoft-agents-testing/docs/README.md	Updates docs README with typed shortcut notes and added guide links.
dev/microsoft-agents-testing/docs/CLI.md	Adds a new CLI guide for agt, including scenario/env/scaffolding commands.
dev/microsoft-agents-testing/docs/ASSERTIONS.md	Adds a comprehensive fluent assertions guide (Expect/Select/matching/lambdas/typed wrappers).
dev/microsoft-agents-testing/docs/API.md	Updates API reference to include typed wrappers, contains, and revised CLI option names.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.