Skip to content

Commit

Permalink
Allow unit test rules to be documented (#343)
Browse files Browse the repository at this point in the history
I find it more ergonomic to add notes or a description about a test to a `doc` attribute, similar to other rules, vs a comment block above it or in the `impl` function docstring. Hopefully this can improve the readability of test rules.
  • Loading branch information
ngiloq6 authored Feb 10, 2022
1 parent 65378a7 commit f796e5e
Show file tree
Hide file tree
Showing 2 changed files with 5 additions and 1 deletion.
3 changes: 2 additions & 1 deletion docs/unittest_doc.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ unittest_toolchain(<a href="#unittest_toolchain-name">name</a>, <a href="#unitte
## analysistest.make

<pre>
analysistest.make(<a href="#analysistest.make-impl">impl</a>, <a href="#analysistest.make-expect_failure">expect_failure</a>, <a href="#analysistest.make-attrs">attrs</a>, <a href="#analysistest.make-fragments">fragments</a>, <a href="#analysistest.make-config_settings">config_settings</a>,
analysistest.make(<a href="#analysistest.make-impl">impl</a>, <a href="#analysistest.make-doc">doc</a>, <a href="#analysistest.make-expect_failure">expect_failure</a>, <a href="#analysistest.make-attrs">attrs</a>, <a href="#analysistest.make-fragments">fragments</a>, <a href="#analysistest.make-config_settings">config_settings</a>,
<a href="#analysistest.make-extra_target_under_test_aspects">extra_target_under_test_aspects</a>)
</pre>

Expand Down Expand Up @@ -73,6 +73,7 @@ Recall that names of test rules must end in `_test`.
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="analysistest.make-impl"></a>impl | The implementation function of the unit test. | none |
| <a id="analysistest.make-doc"></a>doc | A description of the rule that can be extracted by documentation generating tools. | <code>""</code> |
| <a id="analysistest.make-expect_failure"></a>expect_failure | If true, the analysis test will expect the target_under_test to fail. Assertions can be made on the underlying failure using asserts.expect_failure | <code>False</code> |
| <a id="analysistest.make-attrs"></a>attrs | An optional dictionary to supplement the attrs passed to the unit test's <code>rule()</code> constructor. | <code>{}</code> |
| <a id="analysistest.make-fragments"></a>fragments | An optional list of fragment names that can be used to give rules access to language-specific parts of configuration. | <code>[]</code> |
Expand Down
3 changes: 3 additions & 0 deletions lib/unittest.bzl
Original file line number Diff line number Diff line change
Expand Up @@ -206,6 +206,7 @@ _action_retrieving_aspect = aspect(
# TODO(cparsons): Provide more full documentation on analysis testing in README.
def _make_analysis_test(
impl,
doc = "",
expect_failure = False,
attrs = {},
fragments = [],
Expand Down Expand Up @@ -238,6 +239,7 @@ def _make_analysis_test(
Args:
impl: The implementation function of the unit test.
doc: A description of the rule that can be extracted by documentation generating tools.
expect_failure: If true, the analysis test will expect the target_under_test
to fail. Assertions can be made on the underlying failure using asserts.expect_failure
attrs: An optional dictionary to supplement the attrs passed to the
Expand Down Expand Up @@ -277,6 +279,7 @@ def _make_analysis_test(

return rule(
impl,
doc = doc,
attrs = attrs,
fragments = fragments,
test = True,
Expand Down

0 comments on commit f796e5e

Please sign in to comment.