You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: sdk/ai/azure-ai-projects/tests/samples/README.md
+23-13Lines changed: 23 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,14 +1,16 @@
1
-
##Recorded sample tests
1
+
# Recorded sample tests
2
2
3
3
Use recorded tests to validate samples with `SyncSampleExecutor` and `AsyncSampleExecutor`. Tests run the sample code, fail on exceptions, and can optionally validate captured `print` output through LLM instructions.
4
4
5
-
### Prerequisites
5
+
## Prerequisites
6
+
6
7
- In `.env`, set the variables required by your samples plus `AZURE_TEST_RUN_LIVE=true` and `AZURE_SKIP_LIVE_RECORDING=false` when capturing recordings. CI playback typically uses `AZURE_TEST_RUN_LIVE=false` and `AZURE_SKIP_LIVE_RECORDING=true`.
7
8
- Provide sanitized defaults via `servicePreparer` so recordings do not leak secrets. All mandatory environment variables used by the tests/samples must be specified in `servicePreparer` (as sanitized values) so playback can run without access to real secrets.
8
9
9
10
**VS Code tip (record a single sample):** Open the **Testing** tab, expand the pytest tree to find the specific sample test case (for example, one parameterized case for a particular `sample_path`), then right-click it and choose **Run Test** (or **Debug Test**). Make sure your `.env` (or your test run environment) includes `AZURE_TEST_RUN_LIVE=true` and `AZURE_SKIP_LIVE_RECORDING=false` so that run captures a new recording for just that sample.
10
11
11
-
### Sync example
12
+
## Sync example
13
+
12
14
```python
13
15
import pytest
14
16
import os
@@ -49,7 +51,8 @@ class TestSamples(AzureRecordedTestCase):
49
51
)
50
52
```
51
53
52
-
### Async example
54
+
## Async example
55
+
53
56
```python
54
57
import pytest
55
58
from devtools_testutils.aio import recorded_by_proxy_async
@@ -86,9 +89,11 @@ class TestSamplesAsync(AzureRecordedTestCase):
86
89
)
87
90
```
88
91
89
-
### Key pieces
92
+
## Key pieces
93
+
90
94
-`@servicePreparer()`: A custom helper you create for your test suite. It supplies sanitized environment variables for playback (often via `EnvironmentVariableLoader`). The name is up to you; these examples call it `servicePreparer` by convention.
91
95
- Example:
96
+
92
97
```python
93
98
import functools
94
99
from devtools_testutils import EnvironmentVariableLoader
-`@pytest.mark.parametrize`: Drives one test per sample file. Use `samples_to_test` or `samples_to_skip` with `get_sample_paths` / `get_async_sample_paths`.
116
124
-`@SamplePathPasser`: Forwards the sample path to the recorder decorators.
117
125
-`recorded_by_proxy` / `recorded_by_proxy_async`: Wrap tests for recording/playback. Include `RecordedTransport.HTTPX` when samples use httpx in addition to the default `RecordedTransport.AZURE_CORE`.
118
126
-`execute` / `execute_async`: Run the sample; any exception fails the test.
119
127
-`validate_print_calls_by_llm` / `validate_print_calls_by_llm_async`: Optionally validate captured print output with LLM instructions and an explicit `project_endpoint` (and optional `model`).
120
128
-`kwargs` in the test function: A dictionary with environment variables in key and value pairs.
121
129
122
-
### Optional test environment variables mapping
130
+
## Optional test environment variables mapping
131
+
123
132
If you need to remap the environment variable names provided by your fixtures to the names the sample expects, pass a dictionary via the `env_var_mapping` kwarg on the sample executors. When your fixtures already supply the sample-ready names, you can omit `env_var_mapping`.
To run the “hero path” of a sample, your `@servicePreparer` should provide all mandatory environment variables.
135
145
If a sample supports optional environment variables (for optional features/paths), use `@additionalSampleTests` to generate additional recorded test cases with those optional variables set.
-`AdditionalSampleTestDetail.env_vars` is a mapping of **sample env-var name** -> **sanitized playback value**.
173
-
- Live/recording (`AZURE_TEST_RUN_LIVE=true`): reads the real value from your environment (for example, from `.env`) and sanitizes it to the provided playback value.
174
-
- Playback (`AZURE_TEST_RUN_LIVE=false`): sets each key to the provided playback value.
184
+
- Live/recording (`AZURE_TEST_RUN_LIVE=true`): reads the real value from your environment (for example, from `.env`) and sanitizes it to the provided playback value.
185
+
- Playback (`AZURE_TEST_RUN_LIVE=false`): sets each key to the provided playback value.
175
186
-`AdditionalSampleTestDetail.test_id` customizes the parameter id used for that variant.
176
-
- If omitted, the id is auto-generated from the sample filename and env-var keys (for example, `sample_agent_computer_use-[COMPUTER_USE_MODEL_DEPLOYMENT_NAME]`).
177
-
- If provided, it becomes the full parameter id for that variant (no filename prefix).
178
-
- If the auto-generated id makes the recording file path too long (most commonly on Windows), the recording file may fail to generate; set a short `test_id` (and keep it unique across all parametrized cases).
187
+
- If omitted, the id is auto-generated from the sample filename and env-var keys (for example, `sample_agent_computer_use-[COMPUTER_USE_MODEL_DEPLOYMENT_NAME]`).
188
+
- If provided, it becomes the full parameter id for that variant (no filename prefix).
189
+
- If the auto-generated id makes the recording file path too long (most commonly on Windows), the recording file may fail to generate; set a short `test_id` (and keep it unique across all parametrized cases).
179
190
- In VS Code’s **Testing** tab, these show up as additional parameterized cases for the same test, using the parameter id.
0 commit comments