diff --git a/dev/testing/en/continuous-integration.md b/dev/testing/en/continuous-integration.md index 17a0b098fd74..1faae4af34af 100644 --- a/dev/testing/en/continuous-integration.md +++ b/dev/testing/en/continuous-integration.md @@ -4,29 +4,29 @@ title: Continuous Integration - Testing - OJS/OMP # Continuous Integration -We use [Travis CI](https://travis-ci.com) for Continuous Integration (CI) testing. Integration and unit tests are run against every commit and pull request to help catch regressions before they are released. +We use [GitHub Actions](https://github.com/features/actions) for Continuous Integration (CI) testing. Integration and unit tests are run against every pull request to help catch regressions before they are released. -CI tests are configured to run the tests against multiple PHP versions and databases. The configuration details are stored in the `.travis.yml` file in the application's root directory. +CI tests are configured to run the tests against multiple PHP versions and databases. The configuration details are stored in `.github/workflows/main.yml` for each application. -![OJS test results in Travis.](./travis-overview.png) +![OMP test results in GitHub.](./github-actions-overview.png) -View the tests for [OJS](https://travis-ci.com/pkp/ojs/), [OMP](https://travis-ci.com/pkp/omp/) and [OPS](https://travis-ci.com/pkp/ops/). +View the tests for [OJS](https://github.com/pkp/ojs/actions), [OMP](https://github.com/pkp/omp/actions) and [OPS](https://github.com/pkp/ops/actions). ## Tests for pull requests -Travis will run tests against every pull request to OJS or OMP. The tests are listed in the checks at the bottom of the pull request. +GitHub Actions will run tests against every pull request to OJS, OMP, or OPS. The tests are listed in the checks at the bottom of the pull request. -![A Travis check in the pull request.](./travis-pr.png) +![A list of checks in a pull request.](./github-pr.png) -Click the **Details** link beside the Travis tests to watch the tests as they run and see which tests have passed or failed. All tests must pass before a pull request will be merged. +Click the **Details** link beside a test to watch the test as it runs and see which tests have passed or failed. All tests must pass before a pull request will be merged. ### Prepare pull requests for testing -A single change to an application may involve pull requests to more than one repository. For example, a change that impacts `pkp-lib` and `ojs` will require two pull requests. +A change to an application may involve pull requests to more than one repository. For example, a change that impacts `pkp-lib` and `ojs` will require two pull requests. -Travis must be able to locate the correct repository and branch for the `pkp-lib` submodule in order to run the tests against the correct code. To do this, an extra commit with a special commit message, `Submodule update ##/##`, is added to the application repository. +GitHub Actions must be able to locate the correct repository and branch for the `pkp-lib` submodule in order to run the tests against the correct code. To do this, an extra commit with a special commit message, `Submodule update ##/##`, is added to the application repository. -The example below will instruct Travis to clone the `ojs` and `pkp-lib` repositories owned by `NateWr` and check out the `i123_example` branch. +The example below will instruct GitHub Actions to clone the `ojs` and `pkp-lib` repositories owned by `NateWr` and check out the `i123_example` branch. ``` cd path/to/ojs diff --git a/dev/testing/en/debug.md b/dev/testing/en/debug.md index 0839d89b152e..87fdc3c3c099 100644 --- a/dev/testing/en/debug.md +++ b/dev/testing/en/debug.md @@ -4,7 +4,7 @@ title: Debug Test Failures - Testing - OJS/OMP # Debug Test Failures -When a test fails it means that a recent change has broken the application. The log files for the tests will will indicate which tests failed and will list all of the commands that were run before the failure occurred. +When a test fails it means that a recent change has broken the application. The log files for the tests will indicate which tests failed and will list all of the commands that were run before the failure occurred. In most cases, the server's error log will contain important clues about what went wrong. @@ -16,20 +16,20 @@ When the tests are run from the terminal you will find a screenshot of the brows ## Debug CI -The [CI tests](./continuous-integration) can be difficult to debug. Travis provides access to its build logs and screenshots of test failures to help. +The [CI tests](./continuous-integration) can be difficult to debug. GitHub provides access to its build logs and artifacts produced by tests to help. Click **Checks** on a pull request to see the logs from the tests.
-
Short video showing how to access log of build results.
+
Short video showing how to access the log of build results.
This provides a log of the entire build process including the logs from the Cypress and PHP Unit tests. Parts of the log, such as the server's error log, are truncated and can only be reached by accessing the raw log.
Short video showing how to access the raw log of build results.
@@ -37,19 +37,15 @@ This provides a log of the entire build process including the logs from the Cypr > When viewing the raw log, run a search in your browser for "fatal". This is a quick way to find the source of many -- _but not all_ -- test failures. {:.tip} -### Travis debug mode +### Artifacts -Travis provides a [debug mode](https://docs.travis-ci.com/user/running-build-in-debug-mode/). When enabled it is possible to log into the Travis environment via SSH and explore the tests manually. +When a test fails, GitHub Actions will create individual artifact downloads that contain screenshots generated by Cypress for each failing test, as well as server logs. -### Screenshots +![GitHub Actions log with an artifact download URL.](./download-artifacts.png) -Screenshots can be accessed by using the uuencode tool on the Travis VM. To extract the screenshots related to a test failure, follow these steps. +Download URLs will also be output in the logs for each failing test near the end of a test run. -- When viewing the test output on Travis, click the "Raw Log" button. -- Save the log to your computer, for example `/tmp/log.txt`. -- Run `cat /tmp/log.txt | uudecode | tar xvz` to extract the screenshots locally. - -> If you are struggling to understand a test failure in Travis, it may be best to run the tests locally where you have more insight into the state of the application. +> If you are struggling to understand a test failure, it may be best to run the tests locally where you have more insight into the state of the application. {:.tip} --- diff --git a/dev/testing/en/download-artifacts.png b/dev/testing/en/download-artifacts.png new file mode 100644 index 000000000000..cd0966cc491b Binary files /dev/null and b/dev/testing/en/download-artifacts.png differ diff --git a/dev/testing/en/getting-started.md b/dev/testing/en/getting-started.md index b16917e96a9a..d38c550afd44 100644 --- a/dev/testing/en/getting-started.md +++ b/dev/testing/en/getting-started.md @@ -8,7 +8,7 @@ We use [Cypress](https://www.cypress.io/) and [PHPUnit](https://phpunit.de/) to ## Configure your environment -There are many ways to [configure your environment](https://docs.cypress.io/guides/guides/environment-variables.html#Setting) to run the Cypress tests. We recommend creating a `cypress.env.json` file. +There are many ways to [configure your environment](https://docs.cypress.io/guides/guides/environment-variables#Setting) to run the Cypress tests. We recommend creating a `cypress.env.json` file. ```json { @@ -31,7 +31,7 @@ The integration tests will install the software and create test data. ## Run integration tests -The integration tests will install the software and run a number of tests to add users, make submissions, record editorial decisions and publish articles. +The integration tests will install the software and run tests to add users, make submissions, record editorial decisions and publish articles. Before the integration tests are run, update your `config.inc.php` file and set the `installed` flag to `Off`. @@ -41,7 +41,7 @@ Before the integration tests are run, update your `config.inc.php` file and set installed = Off ``` -Run the following comand in the root directory of the application to start a server. The URL should match the `baseUrl` in `cypress.env.json`. +Run the following command in the root directory of the application to start a server. The URL should match the `baseUrl` in `cypress.env.json`. ``` php -S localhost:8000 diff --git a/dev/testing/en/github-actions-overview.png b/dev/testing/en/github-actions-overview.png new file mode 100644 index 000000000000..92482e5ab818 Binary files /dev/null and b/dev/testing/en/github-actions-overview.png differ diff --git a/dev/testing/en/github-log-raw.mp4 b/dev/testing/en/github-log-raw.mp4 new file mode 100644 index 000000000000..34e1fc580939 Binary files /dev/null and b/dev/testing/en/github-log-raw.mp4 differ diff --git a/dev/testing/en/github-log.mp4 b/dev/testing/en/github-log.mp4 new file mode 100644 index 000000000000..e23bba8b540e Binary files /dev/null and b/dev/testing/en/github-log.mp4 differ diff --git a/dev/testing/en/github-pr.png b/dev/testing/en/github-pr.png new file mode 100644 index 000000000000..eeb9a298492a Binary files /dev/null and b/dev/testing/en/github-pr.png differ diff --git a/dev/testing/en/plugins-themes.md b/dev/testing/en/plugins-themes.md index 92913faeef1d..fd880c948508 100644 --- a/dev/testing/en/plugins-themes.md +++ b/dev/testing/en/plugins-themes.md @@ -6,7 +6,7 @@ title: Plugins and Themes - Testing - OJS/OMP Plugins and themes can make use of parts of the application tests to prepare a test environment and run tests. This allows each plugin to implement [continuous integration](./continuous-integration) testing in its own repository. -The [Static Pages](https://github.com/pkp/staticPages/) and [Quick Submit](https://github.com/pkp/quickSubmit) plugins and the [Manuscript](https://github.com/pkp/defaultManuscript) theme are configured for testing. The `.travis.yml` file in each repository configures the integration tests. The tests that are run can be found in each repository's `cypress/tests` directory . +The `.github/workflows/main.yml` file in each repository configures the integration tests. Additional plugin-dependent commands that are run during tests may be found in `.github/actions/tests.sh`. The tests that are run can be found in each repository's `cypress/tests` directory. Plugin and theme tests can be run locally by running the following command in the application's root directory. @@ -14,3 +14,11 @@ Plugin and theme tests can be run locally by running the following command in th cd path/to/ojs npx cypress run --config integrationFolder=plugins/generic/staticPages/cypress/tests ``` + +## Examples + +Examples of plugins that have been configured with tests include: + +- [OAI JATS](https://github.com/pkp/oaiJats) +- [Quick Submit](https://github.com/pkp/quickSubmit) +- The [Manuscript theme](https://github.com/pkp/defaultManuscript) diff --git a/dev/testing/en/travis-log-raw.mp4 b/dev/testing/en/travis-log-raw.mp4 deleted file mode 100644 index 817f9a6eeb21..000000000000 Binary files a/dev/testing/en/travis-log-raw.mp4 and /dev/null differ diff --git a/dev/testing/en/travis-log.mp4 b/dev/testing/en/travis-log.mp4 deleted file mode 100644 index 568d30ee7e34..000000000000 Binary files a/dev/testing/en/travis-log.mp4 and /dev/null differ diff --git a/dev/testing/en/travis-overview.png b/dev/testing/en/travis-overview.png deleted file mode 100644 index aad9ec8092e2..000000000000 Binary files a/dev/testing/en/travis-overview.png and /dev/null differ diff --git a/dev/testing/en/travis-pr.png b/dev/testing/en/travis-pr.png deleted file mode 100644 index 0ae6e555a5b7..000000000000 Binary files a/dev/testing/en/travis-pr.png and /dev/null differ diff --git a/dev/testing/en/writing-tests.md b/dev/testing/en/writing-tests.md index 6fff5f0df82e..6c7f1656b5ff 100644 --- a/dev/testing/en/writing-tests.md +++ b/dev/testing/en/writing-tests.md @@ -11,7 +11,7 @@ It is often appropriate to add to one of the existing tests rather than create a > If you are writing a test which checks a particular part of the editorial workflow, it should be put in `cypress/tests/data`. If you are writing a test for something else, such as statistics or journal settings, it should be put in `cypress/tests/integration`. {:.notice} -Read the Cypress documentation to learn how to write your [first test](https://docs.cypress.io/guides/getting-started/writing-your-first-test.html), [organize tests](https://docs.cypress.io/guides/core-concepts/writing-and-organizing-tests.html#Test-Structure), and [interact with buttons and fields](https://docs.cypress.io/guides/core-concepts/interacting-with-elements.html#Actionability). +Read the Cypress documentation to learn how to write your [first test](https://docs.cypress.io/guides/end-to-end-testing/writing-your-first-end-to-end-test), [organize tests](https://docs.cypress.io/guides/core-concepts/writing-and-organizing-tests#Test-Structure), and [interact with buttons and fields](https://docs.cypress.io/guides/core-concepts/interacting-with-elements#Actionability). ## Commands