Testing Filters

The Online Filters page mentions the existence of a test folder. While Regolith doesn’t provide a built-in testing framework, here’s a recommended approach to set up and test your online filters effectively.

We suggest using the test folder as a dedicated space to store a testing Regolith project. This project should contain test cases that verify your filter’s functionality. Follow these steps to set up your test environment:

1. Create a new Regolith project in the test folder by running:

regolith init

2. Set the export target to local. This prevents Regolith from exporting files to the default com.mojang folder.

Here’s the refined and formatted version of the “Testing Filters” section:

3. Add the build folder to your .gitignore file to keep unnecessary build artifacts out of your repository.

4. Install the Filter Tester filter using:

regolith install filter_tester

The Filter Tester verifies the Regolith output against a predefined set of expected results.

5. Define your online filter as a local filter in the project by referencing its script. You can use .. in the path to point to the parent folder where the filter resides. For example:

"filterDefinitions": {
    "example_filter": {
        "runWith": "python",
        "script": "../example.py"
    }
}

This configuration assumes the filter script is in the parent directory under the file example.py.

6. The Filter Tester can stop execution when the output of your filter doesn’t match the expected results (see the Filter Tester README).

This setting is useful when you want to setup CI on your repository. If you set the filter not to stop on error, you can run the tests and see the differences as errors in the console.

When writing the tests, simply add example inputs to your test project, run Regolith and check the output in the build folder. If the output matches the expectations, copy it to the RP and BP folders inside the data folder of the filter_tester filter.

Note

Refer to this repository for an example project that follows these steps.