Skip to main content

filter.helper: Testing data filtering

Enterprise OPA provides a high-level filter.helper() built-in function for example-based testing of data filter policies.It can be used by importing

import data.system.eopa.utils.tests.v1.filter

See the explanation on testing data filtering for more usage information.

filter.helper

Example Usage

package filters

import data.system.eopa.utils.tests.v1.filter

fruits_table := [
{"id": 0, "name": "apple", "owner_id": "a"},
{"id": 1, "name": "banana", "owner_id": "a"},
{"id": 2, "name": "cherry", "owner_id": "b"},
]

users_table := [
{"id": "a", "name": "jane"},
{"id": "b", "name": "john"},
]

test_owner_can_see_their_fruit if {
filtered := filter.helper(
"data.filters.include",
"SELECT fruits.name, users.name as owner FROM fruits LEFT JOIN users ON fruits.owner_id = users.id",
{
"fruits": fruits_table,
"users": users_table,
},
{
"debug": true
}
) with input.username as "jane"
count(filtered) == 2
{"name": "apple", "owner": "jane"} in filtered
{"name": "banana", "owner": "jane"} in filtered
}

Arguments

It takes four arguments:

PositionParameterDescriptionExample
1filter_ruleThe data reference of the filter rule.data.filters.include
2sql_queryThe query to which filters are to be appended.SELECT fruits.name, users.name as owner FROM fruits LEFT JOIN users ON fruits.owner_id = users.id
3tablesAn object of one or more tables, {"table_name": [<row objects>]}{"fruits": [{"name": "banana"}, {"name": "cherry"}]}
4optsAn object of extra options, see below.

opts supports the following parameters:

ParameterTypeDescriptionRequired (default)Example
debugBoolEnable printing debug output. Only visible in eopa test -v or on test failure.No (false){"debug": true}
dbStringFile name of SQLite3 database to write to.No (:memory:){"db": "temp.sqlite3"}
mappingsObjectA mappings object. See rego.compile() for details.No ({}){"fruits": {"$self": "f", "name": "name_col"}}
warning

When a custom database file name is provided like this, the helper will not drop tables at the end of a test run, allowing you to inspect the intermediate state of your database after eopa test has run.

However, this means that a subsequent run will not start with a fresh database. It is up to the user to remove the temporary database file between runs.

Outputs

filter.helper() returns an array of row objects corresponding to the result of the sql_query combined with the generated filters from your data filter policy. For example:

[
{
"name": "apple",
"owner": "jane"
},
{
"name": "banana",
"owner": "jane"
}
]