docs: Add example test case implementation

Signed-off-by: Torin Sandall <torinsandall@gmail.com>

docs/devel/DEVELOPMENT.md

@@ -38,7 +38,7 @@ with `make check`.
    into your account by clicking the "Fork" button.
 
 1. Clone the fork to your local machine.
-    
+
     ```bash
     # Note: With Go modules this repo can be in _any_ location,
     # and does not need to be in the GOSRC path.
@@ -72,12 +72,12 @@ with `make check`.
     git commit -s
     git push origin somefeature
     ```
-   
+
    > Make sure to use a [good commit message](../../CONTRIBUTING.md#commit-messages)
 
 1. Submit a Pull Request from your fork. See the official [GitHub Documentation](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork)
    for instructions to create the request.
-   
+
     > Hint: You should be prompted to with a "Compare and Pull Request" button
       that mentions your new branch on [https://github.com/open-policy-agent/opa](https://github.com/open-policy-agent/opa)
 
@@ -87,6 +87,18 @@ with `make check`.
 
    > If you are not familiar with squashing commits, see [the following blog post for a good overview](http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html).
 
+## Built-in Functions
+
+[Built-in Functions](https://www.openpolicyagent.org/docs/latest/policy-reference/#built-in-functions)
+can be added inside the `topdown` package in this repository.
+
+Built-in functions may be upstreamed if they are generally useful and provide functionality that would be
+impractical to implement natively in Rego (e.g., CIDR arithmetic). Implementations should avoid thirdparty
+dependencies. If absolutely necessary, consider importing the code manually into the `internal` package.
+
+All built-in function implementations must include a test suite. See [topdown/testdata/cases/helloworld](https://github.com/open-policy-agent/opa/blob/master/topdown/testdata/cases/helloworld)
+in this repository for an example of how to implement tests for your built-in functions.
+
 ## Benchmarks
 
 Several packages in this repository implement benchmark tests. To execute the

topdown/testdata/cases/helloworld/test-helloworld-1.yaml

@@ -0,0 +1,47 @@
+# This file shows how to implement test cases for Rego evaluation.
+#
+# If you are adding new built-in functions to Rego, you must include test cases in this format.
+#
+# Each test file contains a set of test 'cases'. Each test case includes a globally unique
+# name that identifies the test case ('note'), a policy 'query' to execute, and a set of
+# expectations (e.g., 'want_result'). Test cases can also assert on error conditions (e.g.,
+# built-in function errors like divide-by-zero).
+#
+#  * Test cases may include zero or more Rego modules that support the test case.
+#  * Test cases may set the value of the base documents loaded under 'data' and 'input'.
+#
+# The result set is unordered. Each element in the result set specifies variable assignments to
+# expect from the query. The example below finds a single assignment of the number '7' to the
+# variable 'x'.
+#
+# If you adding tests for a built-in function, prefix the note with the built-in function name.
+# Use snake_case_for_the_note.
+#
+# Many of the test cases include a large blob of generic JSON data. This is an artifact
+# of the source code where those cases were exported from. Do not copy the blob into new
+# test cases.
+#
+# The OPA test suite (which is implemented using Go's standard testing framework) discovers tests
+# added under ./topdown/testdata/cases. For example, to run only the tests in this file:
+#
+#   go test ./topdown -v -run 'TestRego/helloworld'
+#
+cases:
+- note: helloworld/test_case
+  query: data.test.p = x
+  modules:
+  - |
+    package test
+
+    p = 7 {
+      data.foo == q
+    }
+
+    q = input.baz
+  data: {"foo": "bar"}
+  input: {"baz": "bar"}
+  want_result: [{x: 7}]
+- note: helloworld/another_test_for_builtin_error
+  query: 1 / 0
+  want_error_code: eval_builtin_error
+  want_error: 'div: divide by zero'