Update testing dev docs to GitHub Actions (#1251)

pkp · Oct 7, 2024 · 4d4a729 · 4d4a729
1 parent 48c9b29
commit 4d4a729
Show file tree

Hide file tree

Showing 14 changed files with 33 additions and 29 deletions.
diff --git 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 ##<username>/<branch>##`,  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 ##<username>/<branch>##`, 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
@@ -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,40 +16,36 @@ 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.
 
 <figure class="video_container">
   <video controls="true" allowfullscreen="true">
-    <source src="./travis-log.mp4" type="video/mp4">
+    <source src="./github-log.mp4" type="video/mp4">
   </video>
-  <figcaption>Short video showing how to access log of build results.</figcaption>
+  <figcaption>Short video showing how to access the log of build results.</figcaption>
 </figure>
 
 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.
 
 <figure class="video_container">
   <video controls="true" allowfullscreen="true">
-    <source src="./travis-log-raw.mp4" type="video/mp4">
+    <source src="./github-log-raw.mp4" type="video/mp4">
   </video>
   <figcaption>Short video showing how to access the raw log of build results.</figcaption>
 </figure>
 
 > 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
diff --git 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
diff --git a/dev/testing/en/github-log-raw.mp4 b/dev/testing/en/github-log-raw.mp4
diff --git a/dev/testing/en/github-log.mp4 b/dev/testing/en/github-log.mp4
diff --git a/dev/testing/en/github-pr.png b/dev/testing/en/github-pr.png
diff --git a/dev/testing/en/plugins-themes.md b/dev/testing/en/plugins-themes.md
@@ -6,11 +6,19 @@ 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.
 
 ```
 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
diff --git a/dev/testing/en/travis-log.mp4 b/dev/testing/en/travis-log.mp4
diff --git a/dev/testing/en/travis-overview.png b/dev/testing/en/travis-overview.png
diff --git a/dev/testing/en/travis-pr.png b/dev/testing/en/travis-pr.png
diff --git 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