Skip to content

Add documentation on automated testing for extensions #480

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 2 commits into
base: master
Choose a base branch
from
Open

Add documentation on automated testing for extensions #480

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
00f2f29
Initial draft of extension testing documentation
SoryRawyer Aug 27, 2025
69cf852
include additional references for CI/CD
SoryRawyer Aug 27, 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
12 changes: 12 additions & 0 deletions docs/technical-reference/writing-extensions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -343,3 +343,15 @@ Packages.com.google.refine.expr.MetaParser.registerLanguageParser(

The first string is the prefix that gets prepended to each expression so that we know which language the expression is in. This should be short, unique, and identifying. The second string is a user-friendly name of the language. The third is an object that implements the interface `com.google.refine.expr.LanguageSpecificParser`. The final string is the default expression in that language that would return the cell's value.

## Testing

Like OpenRefine core, extensions can test backend code through Java unit tests and frontend/integration tests can be written using Cypress. In addition to the resources below, extension authors are encouraged to review the documentation related to [functional tests](https://openrefine.org/docs/technical-reference/functional-tests) in OpenRefine core.

Please note that Java unit tests can be run from the command line with no additional setup, but integration tests need to have a running instance of OpenRefine to test against.

### Java unit testing
The sample extension template includes a reference unit test suite which leverages [the `RefineTest` base class](https://github.com/OpenRefine/OpenRefine/blob/master/modules/core/src/test/java/com/google/refine/RefineTest.java) provided by OpenRefine core. Tests are not required to extend `RefineTest`, but that class provides many utilities that may help you test your extension.

### End to end testing in Cypress
OpenRefine uses [Cypress](https://www.cypress.io/) to automate frontend and integration testing. To get started with end-to-end testing, [this guide in the Cypress docs](https://docs.cypress.io/app/end-to-end-testing/writing-your-first-end-to-end-test) may be helpful. The [documentation for OpenRefine's functional tests](https://openrefine.org/docs/technical-reference/functional-tests) also provides guidance for writing Cypress tests. For reference, please see the [Cypress tests in OpenRefine core](https://github.com/OpenRefine/OpenRefine/tree/master/main/tests/cypress) and the [Cypress tests in CommonsExtension](https://github.com/OpenRefine/CommonsExtension/tree/master/cypress).
Cypress can also be run in headless mode, enabling end-to-end tests in CI/CD pipelines. The documentation for this feature can be found [on the Cypress website](https://docs.cypress.io/app/continuous-integration/overview) and an example script for running end-to-end tests can be found in [the `refine` shell script](https://github.com/OpenRefine/OpenRefine/blob/master/refine#L364-L443).