diff --git a/docs/developer/from-source.md b/docs/developer/from-source.md index 27cd57f8..4ac0574d 100644 --- a/docs/developer/from-source.md +++ b/docs/developer/from-source.md @@ -134,26 +134,6 @@ docker buildx build . This will run the entire build process in a Docker container with the required dependencies. You can also supply a tag during the build process with the `-t` option, to make it easier to publish or run the image later. -### Test +### Testing -After following the steps above, a `forgejo` binary will be available in the working directory. -It can be tested from this directory or moved to a directory with test data. When Forgejo is -launched manually from command line, it can be killed by pressing `Ctrl + C`. - -```bash -./forgejo web -``` - -To run and continuously rebuild when the source files change: - -```bash -TAGS='sqlite sqlite_unlock_notify' make watch -``` - -> **NOTE:** do not set the `bindata` tag such as in `TAGS="bindata" make watch` or the browser may fail to load pages with an error like `Failed to load asset` - -To run automated frontend and backend tests: - -```bash -make test -``` +See [the section dedicated to testing](./testing/). diff --git a/docs/developer/index.md b/docs/developer/index.md index 6da343e9..75fa6de5 100644 --- a/docs/developer/index.md +++ b/docs/developer/index.md @@ -12,6 +12,7 @@ their needs. - [Sustainability and funding](https://codeberg.org/forgejo/sustainability) - For contributors - [Compiling from source](./from-source/) + - [Testing](./testing/) - [Development environment](./development-environment/) - [Interface customization](./customization/) - [Architecture overview](./architecture/) diff --git a/docs/developer/testing.md b/docs/developer/testing.md new file mode 100644 index 00000000..9a76cdf1 --- /dev/null +++ b/docs/developer/testing.md @@ -0,0 +1,121 @@ +--- +title: 'Testing' +license: 'CC-BY-SA-4.0' +--- + +A [reasonable effort should be made to test changes](https://codeberg.org/forgejo/governance/src/branch/main/PullRequestsAgreement.md) +proposed to Forgejo. + +## Running the tests from sources + +To run automated frontend and backend tests: + +```bash +make test +``` + +## Frontend tests + +The [e2e](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/tests/e2e/README.md) frontend tests are run with: + +```sh +make 'test-e2e-sqlite' +# or, for individual tests +make 'test-e2e-sqlite#example.test' +``` + +They are based on [playwright](https://playwright.dev/) and will: + +- Launch a Forgejo instance +- Populate it with data found in the `models/fixtures` directory +- Launch a browser (e.g. Firefox) +- Run JavaScript tests (e.g. tests/e2e/example.test.e2e.js) + +> **NOTE:** make sure to [use a version of Node >= 20.11.1](https://github.com/microsoft/playwright/issues/29253) + +### With VSCodium or VSCode + +To debug a test, you can use "Playwright Test" for +[VScodium](https://open-vsx.org/extension/ms-playwright/playwright) +or [VSCode](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright). +Before doing that you will need to manually start a Forgejo instance and populate it +with data from `models/fixtures` by running: + +```sh +make TAGS='sqlite sqlite_unlock_notify' 'test-e2e-debugserver' +``` + +### CLI + +Tests can also be individually run on an existing server as follows: + +```sh +GITEA_URL=http://0.0.0.0:3000 npx playwright test tests/e2e/release.test.e2e.js +``` + +In this case the Forgejo instance must be manually prepared with a minimal +subset of the data found in the `models/fixtures` directory. + +## Interactive testing + +To run and continuously rebuild when the source files change: + +```bash +TAGS='sqlite sqlite_unlock_notify' make watch +``` + +> **NOTE:** do not set the `bindata` tag such as in `TAGS="bindata" make watch` or the browser may fail to load pages with an error like `Failed to load asset` + +## Manual run of the binary + +After following the [steps to compile from source](../from-source/), a `forgejo` binary will be available +in the working directory. +It can be tested from this directory or moved to a directory with test data. When Forgejo is +launched manually from command line, it can be killed by pressing `Ctrl + C`. + +```bash +./forgejo web +``` + +## Automated tests + +### In the Forgejo repository + +When a [pull request](https://codeberg.org/forgejo/forgejo/pulls) is opened, +it will run workflows found in the [.forgejo/workflows](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/.forgejo/workflows) +directory. + +### In the end-to-end repository + +Some tests are best served by running Forgejo from a compiled binary, +for instance to verify the result of a workflow run by the [Forgejo runner](https://code.forgejo.org/forgejo/runner). They can be +run by adding the `run-end-to-end-test` label to the pull request. It will: + +- compile a binary from the pull request +- open a pull request against the [end-to-end](https://code.forgejo.org/forgejo/end-to-end) repository +- use the compiled binary to run the tests +- report back failure or success + +### Debugging locally + +A workflow can be run locally by [installing the Forgejo runner](../../admin/actions/#installation) and using the command line: + +```sh +forgejo-runner exec --workflows .forgejo/workflows/testing.yml +``` + +## Manual testing + +When the change to be tested lacks the proper framework, the manual +test procedure must be documented and referenced in the +[manual testing repository](https://codeberg.org/forgejo/forgejo-manual-testing). +The tests it contains should be run on a regular basis to verify they keep working. + +Changes that are associated with a manual test procedure should be +labeled ["manual test"](https://codeberg.org/forgejo/forgejo/pulls?labels=181437). + +## No test + +When a change is not tested, it should be labeled +["untested"](https://codeberg.org/forgejo/forgejo/pulls?labels=167348). The +rationale for the absence of test should be explained.