From 00f2f29f8517e410d7c6dcb1722281a30408e5f8 Mon Sep 17 00:00:00 2001 From: Rory Sawyer Date: Wed, 27 Aug 2025 16:44:05 -0400 Subject: [PATCH 1/2] Initial draft of extension testing documentation --- docs/technical-reference/writing-extensions.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/technical-reference/writing-extensions.md b/docs/technical-reference/writing-extensions.md index c7a44d09..7564deb0 100644 --- a/docs/technical-reference/writing-extensions.md +++ b/docs/technical-reference/writing-extensions.md @@ -343,3 +343,13 @@ 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. + +### 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 tests 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. From 69cf852170f2f7d4915d06472dd727554bee30c4 Mon Sep 17 00:00:00 2001 From: Rory Sawyer Date: Wed, 27 Aug 2025 16:50:00 -0400 Subject: [PATCH 2/2] include additional references for CI/CD --- docs/technical-reference/writing-extensions.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/technical-reference/writing-extensions.md b/docs/technical-reference/writing-extensions.md index 7564deb0..14ad35b8 100644 --- a/docs/technical-reference/writing-extensions.md +++ b/docs/technical-reference/writing-extensions.md @@ -347,9 +347,11 @@ The first string is the prefix that gets prepended to each expression so that we 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 tests in Cypress +### 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. +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).