From f039068b13f5d8ee3c6eb449fcd181b2e1f8c2df Mon Sep 17 00:00:00 2001
From: godofredoc <godofredoc@google.com>
Date: Wed, 21 Jun 2023 09:43:33 -0700
Subject: [PATCH] Document the use of contexts on engine_v2 tests.
 (flutter/engine#43013)

Contexts are predefined python contexts that can be dynamically added to the test execution.

Bug: https://github.com/flutter/flutter/issues/129187

[C++, Objective-C, Java style guides]: https://github.com/flutter/engine/blob/main/CONTRIBUTING.md#style
---
 engine/src/flutter/ci/builders/README.md | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/engine/src/flutter/ci/builders/README.md b/engine/src/flutter/ci/builders/README.md
index eb715a8c5b1..5a5133475ee 100644
--- a/engine/src/flutter/ci/builders/README.md
+++ b/engine/src/flutter/ci/builders/README.md
@@ -283,7 +283,8 @@ configuration.
            "impeller-vulkan",
            "--engine-capture-core-dump"
        ],
-       "script": "flutter/testing/run_tests.py"
+       "script": "flutter/testing/run_tests.py",
+       "contexts": ["android_virtual_device"]
    }
 ]
 ```
@@ -299,6 +300,9 @@ permissions to run in the target platform.
 * **parameters** - flags or parameters passed to the script.
 * **Script** - the path to the script to execute relative to the checkout
 directory.
+* **contexts** - a list of available contexts to add to the text execution step.
+The list of supported contexts can be found [here](https://flutter.googlesource.com/recipes/+/refs/heads/main/recipe_modules/flutter_deps/api.py#687). As of 06/20/23 two contexts are supported:
+"android_virtual_device" and "metric_center_token".
 
 The test scripts will run in a deferred context (failing the step only after
 logs have been uploaded). Tester and builder recipes provide an environment
@@ -307,6 +311,10 @@ test runner can place any logs|artifacts needed to debug issues. At the end
 of the test execution the content of FLUTTER\_LOGS\_DIR will be uploaded to
 Google Cloud Storage before signaling the pass | fail test state.
 
+Contexts are free form python contexts that communicate with the test script
+through environment variables. E.g. metric_center_token saves an access token
+to an [environment variable "token_path"](https://flutter.googlesource.com/recipes/+/refs/heads/main/recipe_modules/token_util/api.py#14) for the test to access it.
+
 Note that to keep the recipes generic they don’t know anything about what
 the test script is doing and it is the responsibility of the test script to
 copy the relevant files to the FLUTTER\_LOGS\_DIR directory.