Skip to content

feat: documentation changes for multiple tuple files support in tests #1050

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

feat: documentation changes for multiple tuple files support in tests #1050

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
03d09a8
feat: documentation changes for multiple tuple files support in tests
SoulPancake Jun 12, 2025
cf252bf
feat: include tuple_files in all sections of doc
SoulPancake Jun 12, 2025
ee0e65d
feat: only code fmt the cmd obj
SoulPancake Jun 12, 2025
84d2e61
feat: rephrase example comment
SoulPancake Jun 12, 2025
fe1f3e2
Merge branch 'main' into patch-1
SoulPancake Jun 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 15 additions & 5 deletions docs/content/modeling/testing-models.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ The `.fga.yaml` contains tests for <ProductName format={ProductNameFormat.ShortF
| -------- | -------- |
| `name` (optional) | A descriptive name for the test file |
| `model` or `model_file` | An <ProductName format={ProductNameFormat.ShortForm}/> model or a reference to an external model file in `fga`, `json` or `mod` format |
|`tuples or tuple_file` (optional) | A set of tuples or a reference to an external tuple file in `json`, `yaml` or `csv` format. These are considered for all tests. |
|`tuples` or `tuple_file` or multiple `tuple_files` (optional) | A set of tuples or a reference to an external tuple file in `json`, `yaml` or `csv` format. These are considered for all tests. |
|`tests` | A set of tests that verify the return values of <ProductName format={ProductNameFormat.ShortForm}/> API calls |

The example below defines a model and tuples:
Expand All @@ -51,8 +51,18 @@ model: |
current_time < grant_time + grant_duration
}

# tuple_file: ./tuples.yaml # you can specify an external file, include it inline, or both
tuples:
# You can provide relationship tuples in one of the following ways:
# - As a single external file using 'tuple_file'
# - As multiple external files using 'tuple_files'
# - Inline directly using 'tuples'
#
# Examples:
# tuple_file: ./tuples.yaml # Single external file
# tuple_files: # Multiple external files
# - ./tuples_2.yaml
# - ./tuples_3.yaml
tuples: # Inline tuple definitions go here


# Anne is a member of the Acme organization
- user: user:anne
Expand All @@ -79,7 +89,7 @@ Tests have the following structure:
| Object | Description |
| -------- | -------- |
|`name` (optional) | A descriptive name for the test, like “Organization Membership” |
|`tuple_file` or `tuples` | A set of tuples that are only considered for the test |
|`tuple_file` or `tuple_files` or `tuples` | A set of tuples that are only considered for the test |
|`check` | A set of tests for Check calls, each with a user/object and a set of assertions |
|`list_objects` | A set of tests for ListObjects calls, each one with a user/type and a set of assertions for any number of relations|
|`list_users` | A set of tests for ListUsers calls, each one with an object and user filter and a set of assertions for the users for any number of relations |
Expand Down Expand Up @@ -191,7 +201,7 @@ The example above checks that the `organization:acme`, given the current time is

If you are using [Modular Models](./modular-models.mdx), you need to use the `fga.mod` as the `model_file`.

You can define the tests for each model in separate `.fga.yaml` files. All files should point to the `fga.mod` model. You can create a shared file with tuples and reference it with the `tuple_file` option. You can include module-specific tuples in each `fga.yaml` file.
You can define tests for each model in separate `.fga.yaml` files, all of which should reference the common `fga.mod` model. Shared relationship tuples can be placed in a separate file and included using the `tuple_file` option. If needed, you can split tuples across multiple shared files and include them with the `tuple_files` option. Additionally, each `.fga.yaml` file can include module-specific tuples inline.

## Running tests

Expand Down