Add support for App Language and App Region scheme test action options (#3105)

Added support for `language` and `region`. This can be done through the
auto scheme generation using `autogeneration_config`:

```
xcodeproj(
        …
        scheme_autogeneration_config = xcschemes.autogeneration_config(
             test = xcschemes.autogeneration.test(
                 test_options = xcschemes.test_options(
                     app_language = "en",
                     app_region = "US",
                 )
             )
        ),
        …
)
``` 

or by providing an options struct in a custom scheme:

```
xcschemes.scheme(
        …
        test = xcschemes.test(
            …
            test_options = xcschemes.test_options(
                app_language = "en",
                app_region = "US",
            ),
            …
        ),
        …
)
```

These configurations will add the appropriate tags to the `<TestAction>`
tag.

Corresponding settings in Xcode:
<img width="500"
src="https://github.com/user-attachments/assets/9bef3d96-99bf-4b20-92a0-2b8548766783">

---------

Signed-off-by: longsview <longsview@gmail.com>
Signed-off-by: Brentley Jones <github@brentleyjones.com>
Signed-off-by: Nicholas Long <longsview@gmail.com>
Co-authored-by: Brentley Jones <github@brentleyjones.com>
Co-authored-by: Chuck Grindel <chuck.grindel@gmail.com>

Author: 3 people

CONTRIBUTING.md

@@ -31,6 +31,9 @@ projects with `bazel run //examples/cc:xcodeproj`. You might need to `cd`
 into the directory if the example app is in a separate `WORKSPACE` with
 `cd examples/integration; bazel run //:xcodeproj`.
 
+You can run the internal tests as well:
+`bazel test //test/internal/xcschemes:all`
+
 You can even test your changes in a separate project living outside this
 repo by overriding the module or repository in your `.bazelrc`.
 ```
@@ -50,3 +53,17 @@ You can do so with `./test/update_all_fixtures.sh`.
 All of the test fixture projects aren't buildable, because we use empty files in
 place of things that are the same in every project. If you need to verify
 anything in those projects, regenerate them locally.
+
+## Updating docs
+
+Run `./docs/update_docs.sh` to generate to documentation based on the comments.
+
+## Linting and formatting
+
+Before submitting your PR you should run the linter and formatter to
+make sure everything if formatted properly in your bazel files
+
+`bazel run //:buildifier.fix`
+
+you can run `bazel run //:buildifier.check` to make sure your formatting
+is correct.

docs/bazel.md

@@ -240,12 +240,36 @@ Defines a command-line argument.
 | <a id="xcschemes.arg-literal_string"></a>literal_string |  Whether `value` should be interpreted as a literal string.<br><br>If `True`, any spaces will be escaped. This means that `value` will be passed to the launch target as a single string. If `False`, any spaces will not be escaped. This is useful to group multiple arguments under a single checkbox in Xcode.   |  `True` |
 
 
+<a id="xcschemes.autogeneration.test"></a>
+
+## xcschemes.autogeneration.test
+
+<pre>
+xcschemes.autogeneration.test(<a href="#xcschemes.autogeneration.test-options">options</a>)
+</pre>
+
+Creates a value for the `test` argument of `xcschemes.autogeneration_config`.
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="xcschemes.autogeneration.test-options"></a>options |  Test options for autogeneration.<br><br>Defaults to `None`.   |  `None` |
+
+**RETURNS**
+
+An opaque value for the
+  [`test`](user-content-xcschemes.autogeneration_config-test)
+  argument of `xcschemes.autogeneration_config`.
+
+
 <a id="xcschemes.autogeneration_config"></a>
 
 ## xcschemes.autogeneration_config
 
 <pre>
-xcschemes.autogeneration_config(<a href="#xcschemes.autogeneration_config-scheme_name_exclude_patterns">scheme_name_exclude_patterns</a>)
+xcschemes.autogeneration_config(<a href="#xcschemes.autogeneration_config-scheme_name_exclude_patterns">scheme_name_exclude_patterns</a>, <a href="#xcschemes.autogeneration_config-test">test</a>)
 </pre>
 
 Creates a value for the [`scheme_autogeneration_config`](xcodeproj-scheme_autogeneration_config) attribute of `xcodeproj`.
@@ -255,7 +279,8 @@ Creates a value for the [`scheme_autogeneration_config`](xcodeproj-scheme_autoge
 
 | Name  | Description | Default Value |
 | :------------- | :------------- | :------------- |
-| <a id="xcschemes.autogeneration_config-scheme_name_exclude_patterns"></a>scheme_name_exclude_patterns |  A `list` of regex patterns used to skip creating matching autogenerated schemes.<br><br>Example:<br><br><pre><code class="language-starlark">xcodeproj(&#10;    ...&#10;    scheme_name_exclude_patterns = xcschemes.autogeneration_config(&#10;        scheme_name_exclude_patterns = [&#10;            ".*somePattern.*",&#10;            "^AnotherPattern.*",&#10;        ],&#10;    )&#10;)</code></pre>   |  `None` |
+| <a id="xcschemes.autogeneration_config-scheme_name_exclude_patterns"></a>scheme_name_exclude_patterns |  A `list` of regex patterns used to skip creating matching autogenerated schemes.<br><br>Example:<br><br><pre><code class="language-starlark">xcodeproj(&#10;    ...&#10;    scheme_name_exclude_patterns = xcschemes.autogeneration_config(&#10;        scheme_name_exclude_patterns = [&#10;            ".*somePattern.*",&#10;            "^AnotherPattern.*",&#10;        ],&#10;    ),&#10;)</code></pre>   |  `None` |
+| <a id="xcschemes.autogeneration_config-test"></a>test |  Options to use for the test action.<br><br>Example:<br><br>```starlark xcodeproj(     ...     scheme_autogeneration_config = xcschemes.autogeneration_config(         test = xcschemes.autogeneration.test(             options = xcschemes.test_options(                 app_language = "en",                 app_region = "US",             )         )     ) )   |  `None` |
 
 **RETURNS**
 
@@ -499,8 +524,8 @@ Defines a custom scheme.
 ## xcschemes.test
 
 <pre>
-xcschemes.test(<a href="#xcschemes.test-args">args</a>, <a href="#xcschemes.test-build_targets">build_targets</a>, <a href="#xcschemes.test-diagnostics">diagnostics</a>, <a href="#xcschemes.test-env">env</a>, <a href="#xcschemes.test-env_include_defaults">env_include_defaults</a>, <a href="#xcschemes.test-test_targets">test_targets</a>,
-               <a href="#xcschemes.test-use_run_args_and_env">use_run_args_and_env</a>, <a href="#xcschemes.test-xcode_configuration">xcode_configuration</a>)
+xcschemes.test(<a href="#xcschemes.test-args">args</a>, <a href="#xcschemes.test-build_targets">build_targets</a>, <a href="#xcschemes.test-diagnostics">diagnostics</a>, <a href="#xcschemes.test-env">env</a>, <a href="#xcschemes.test-env_include_defaults">env_include_defaults</a>, <a href="#xcschemes.test-test_options">test_options</a>,
+               <a href="#xcschemes.test-test_targets">test_targets</a>, <a href="#xcschemes.test-use_run_args_and_env">use_run_args_and_env</a>, <a href="#xcschemes.test-xcode_configuration">xcode_configuration</a>)
 </pre>
 
 Defines the Test action.
@@ -515,11 +540,31 @@ Defines the Test action.
 | <a id="xcschemes.test-diagnostics"></a>diagnostics |  The diagnostics to enable when testing.<br><br>Can be `None` or a value returned by [`xcschemes.diagnostics`](#xcschemes.diagnostics). If `None`, `xcschemes.diagnostics()` will be used, which means no diagnostics will be enabled.   |  `None` |
 | <a id="xcschemes.test-env"></a>env |  Environment variables to use when testing.<br><br>If set to `"inherit"`, then the environment variables will be supplied by the test targets (e.g. [`ios_unit_test.env`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-ios.md#ios_unit_test-env)), as long as every test target has the same environment variables. Otherwise, the `dict` of environment variables will be set as provided, and `None` or `{}` will result in no environment variables.<br><br>Each value of the `dict` can either be a string or a value returned by [`xcschemes.env_value`](#xcschemes.env_value). If a value is a string, it will be transformed into `xcschemes.env_value(value)`. For example, <pre><code>xcschemes.test(&#10;    env = {&#10;        "VAR1": "value 1",&#10;        "VAR 2": xcschemes.env_value("value2", enabled = False),&#10;    },&#10;)</code></pre> will be transformed into: <pre><code>xcschemes.test(&#10;    env = {&#10;        "VAR1": xcschemes.env_value("value 1"),&#10;        "VAR 2": xcschemes.env_value("value2", enabled = False),&#10;    },&#10;)</code></pre>   |  `"inherit"` |
 | <a id="xcschemes.test-env_include_defaults"></a>env_include_defaults |  Whether to include the rules_xcodeproj provided default Bazel environment variables (e.g. `BUILD_WORKING_DIRECTORY` and `BUILD_WORKSPACE_DIRECTORY`), in addition to any set by [`env`](#xcschemes.test-env).   |  `True` |
+| <a id="xcschemes.test-test_options"></a>test_options |  The test options to set for testing. Can be `None` or a value returned by [`xcschemes.test_options`](#xcschemes.test_options). If `None`, `xcschemes.test_options()` will be used, which means no additional test options be set.   |  `None` |
 | <a id="xcschemes.test-test_targets"></a>test_targets |  The test targets to build, and possibly run, when testing.<br><br>Each element of the `list` can be a label string or a value returned by [`xcschemes.test_target`](#xcschemes.test_target). If an element is a label string, it will be transformed into `xcschemes.test_target(label_str)`. For example, <pre><code>xcschemes.test(&#10;    test_targets = [&#10;        "//App:Test1",&#10;        xcschemes.test_target(&#10;            "//App:Test2",&#10;            &hellip;&#10;        ),&#10;    ],&#10;)</code></pre> will be transformed into: <pre><code>xcschemes.test(&#10;    test_targets = [&#10;        xcschemes.test_target("//App:Test1"),&#10;        xcschemes.test_target(&#10;            "//App:Test2",&#10;            &hellip;&#10;        ),&#10;    ],&#10;)</code></pre>   |  `[]` |
 | <a id="xcschemes.test-use_run_args_and_env"></a>use_run_args_and_env |  Whether the `Use the Run action's arguments and environment variables` checkbox is checked.<br><br>If `True`, command-line arguments and environment variables will still be set as defined by [`args`](#xcschemes.test-args) and [`env`](#xcschemes.test-env), but will be ignored by Xcode unless you manually uncheck this checkbox in the scheme. If `None`, `True` will be used if [`args`](#xcschemes.test-args) and [`env`](#xcschemes.test-env) are both `"inherit"`, otherwise `False` will be used.<br><br>A value of `True` will be ignored (i.e. treated as `False`) if [`run.launch_target`](#xcschemes.run-launch_target) is not set to a target.   |  `None` |
 | <a id="xcschemes.test-xcode_configuration"></a>xcode_configuration |  The name of the Xcode configuration to use to build the targets referenced in the Test action (i.e in the [`build_targets`](#xcschemes.test-build_targets) and [`test_targets`](#xcschemes.test-test_targets) attributes).<br><br>If not set, the value of [`xcodeproj.default_xcode_configuration`](#xcodeproj-default_xcode_configuration) is used.   |  `None` |
 
 
+<a id="xcschemes.test_options"></a>
+
+## xcschemes.test_options
+
+<pre>
+xcschemes.test_options(<a href="#xcschemes.test_options-app_language">app_language</a>, <a href="#xcschemes.test_options-app_region">app_region</a>)
+</pre>
+
+Defines the test options for a custom scheme.
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="xcschemes.test_options-app_language"></a>app_language |  Language to set in scheme.<br><br>Defaults to system settings if not set.   |  `None` |
+| <a id="xcschemes.test_options-app_region"></a>app_region |  Region to set in scheme.<br><br>Defaults to system settings if not set.   |  `None` |
+
+
 <a id="xcschemes.test_target"></a>
 
 ## xcschemes.test_target
@@ -836,7 +881,7 @@ A `struct` representing an Xcode scheme.
 
 <pre>
 xcode_schemes.test_action(<a href="#xcode_schemes.test_action-targets">targets</a>, <a href="#xcode_schemes.test_action-args">args</a>, <a href="#xcode_schemes.test_action-build_configuration">build_configuration</a>, <a href="#xcode_schemes.test_action-diagnostics">diagnostics</a>, <a href="#xcode_schemes.test_action-env">env</a>,
-                          <a href="#xcode_schemes.test_action-expand_variables_based_on">expand_variables_based_on</a>, <a href="#xcode_schemes.test_action-pre_actions">pre_actions</a>, <a href="#xcode_schemes.test_action-post_actions">post_actions</a>)
+                          <a href="#xcode_schemes.test_action-expand_variables_based_on">expand_variables_based_on</a>, <a href="#xcode_schemes.test_action-options">options</a>, <a href="#xcode_schemes.test_action-pre_actions">pre_actions</a>, <a href="#xcode_schemes.test_action-post_actions">post_actions</a>)
 </pre>
 
 Constructs a test action for an Xcode scheme.
@@ -852,6 +897,7 @@ Constructs a test action for an Xcode scheme.
 | <a id="xcode_schemes.test_action-diagnostics"></a>diagnostics |  Optional. A value returned by `xcode_schemes.diagnostics`.   |  `None` |
 | <a id="xcode_schemes.test_action-env"></a>env |  Optional. A `dict` of `string` values that will be set as environment variables when the target is executed.<br><br>If both this and `args` are `None` (not just empty), then the launch action's environment variables will be inherited.   |  `None` |
 | <a id="xcode_schemes.test_action-expand_variables_based_on"></a>expand_variables_based_on |  Optional. One of the specified test target labels.<br><br>If no value is provided, one of the test targets will be selected. If no expansion context is desired, use the `string` value `none`.   |  `None` |
+| <a id="xcode_schemes.test_action-options"></a>options |  Optional. A value returned by `xcode_schemes.test_options`.   |  `None` |
 | <a id="xcode_schemes.test_action-pre_actions"></a>pre_actions |  Optional. A `sequence` of `struct` values as created by `xcode_schemes.pre_post_action`.   |  `[]` |
 | <a id="xcode_schemes.test_action-post_actions"></a>post_actions |  Optional. A `sequence` of `struct` values as created by `xcode_schemes.pre_post_action`.   |  `[]` |
 

examples/integration/test/fixtures/bwb_custom_xcode_schemes.json

@@ -151,6 +151,12 @@ SCHEME_AUTOGENERATION_CONFIG = xcschemes.autogeneration_config(
         ".*UndesiredScheme.*",
         ".*UnwantedScheme.*",
     ],
+    test = xcschemes.autogeneration.test(
+        options = xcschemes.test_options(
+            app_language = "en",
+            app_region = "US",
+        ),
+    ),
 )
 
 def get_xcode_schemes():
@@ -238,6 +244,10 @@ XCSCHEMES = [
             env = {
                 "IOSAPPSWIFTUNITTESTS_CUSTOMSCHEMEVAR": "TRUE",
             },
+            test_options = xcschemes.test_options(
+                app_language = "en",
+                app_region = "US",
+            ),
             test_targets = [
                 "//iOSApp/Test/SwiftUnitTests:iOSAppSwiftUnitTests",
             ],

examples/integration/test/fixtures/generated/xcodeproj_bwb/custom_xcode_schemes.json

@@ -165,6 +165,7 @@ def _test_action_test(ctx):
         diagnostics = None,
         env = None,
         expand_variables_based_on = None,
+        options = None,
         pre_actions = [],
         post_actions = [],
     )
@@ -180,6 +181,7 @@ def _test_action_test(ctx):
         diagnostics = None,
         env = custom_env,
         expand_variables_based_on = None,
+        options = None,
         pre_actions = [],
         post_actions = [],
     )
@@ -198,6 +200,7 @@ def _test_action_test(ctx):
         diagnostics = None,
         env = {},
         expand_variables_based_on = "none",
+        options = None,
         pre_actions = [],
         post_actions = [],
     )
@@ -219,6 +222,7 @@ def _test_action_test(ctx):
         diagnostics = None,
         env = None,
         expand_variables_based_on = bazel_labels.normalize_string(targets[0]),
+        options = None,
         pre_actions = [],
         post_actions = [],
     )