diff --git a/content/project-organization/quality-council/processes/contribute-ui-tests/_index.md b/content/project-organization/quality-council/processes/contribute-ui-tests/_index.md index 8bf923f..6039448 100644 --- a/content/project-organization/quality-council/processes/contribute-ui-tests/_index.md +++ b/content/project-organization/quality-council/processes/contribute-ui-tests/_index.md @@ -4,44 +4,150 @@ title: How to contribute to UI tests # How to contribute to UI tests -## Introduction +## Overview -### Branches +Contributing to UI tests involves the following steps: -The first question to ask when making a contribution is "Which branch should I target?". +1. Selecting a scenario +2. Setting up your environment +3. Writing the test +4. Submitting a Pull Request (PR) +5. Getting it reviewed and merged -The rules are as follows: -* The development branch for UI testing is the current development branch. -* The branch changes as soon as the final release is out. +--- -### Differences between scenarios & tests +## Introduction -Scenarios are the base of UI Tests. They are available on the [PrestaShop Tests Documentation](https://build.prestashop-project.org/test-scenarios/). +Scenarios are the basis of UI tests. They describe expected behaviors in a human-readable format and are available in the [PrestaShop Tests Documentation](https://build.prestashop-project.org/test-scenarios/). -Tests are the code based on scenarios. They are available on the main repository [in the tests/UI directory](https://github.com/PrestaShop/PrestaShop/tree/develop/tests/UI). +Tests are the automated implementations of these scenarios. They are located in the [tests/UI directory of the PrestaShop Core repository](https://github.com/PrestaShop/PrestaShop/tree/develop/tests/UI). + +--- ## Contribute to UI tests -### Choose a scenario to automate - -_**This part is only available for PrestaShopCorp employees.**_ -* Go to the PrestaShop Forge -* Access to the Test Repositoy -* Find a test in the directory `Core` or `Modules` with the state "TO BE AUTOMATED" - -### Create the PR -* The contributor create a PR targetting the development branch for UI tests. -* The contributor can check that the PR works with the [Github Action `ga.tests.ui.pr`](https://github.com/PrestaShop/ga.tests.ui.pr). - -### Review the PR -* The review is done by [Software Developers in Tests of the project](/project-organization/people-and-roles/#software-developers-in-test). -* Some checks are done : - * The PR complies with [contribution guidelines](https://devdocs.prestashop-project.org/9/contribute/contribution-guidelines/); - * The CI is green (lint, typescript check); - * The scenario is followed; - * The test is executed without errors in the [nightly](https://github.com/PrestaShop/ga.tests.ui.pr); - * The test use the Page Object Model pattern. - -### Merge of the PR -* The merge is done after two approvals of [Software Developers in Tests of the project](/project-organization/people-and-roles/#software-developers-in-test) including a maintainer. -* After that, the contribution will be executed every night in the [nightly of the project](https://nightly.prestashop-project.org/) to ensure continuity and stability of the project. \ No newline at end of file +### 1. Choose a scenario to automate + +* Go to the [`test-scenarios` repository](https://github.com/PrestaShop/test-scenarios/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22STATE%20%3A%20To%20Be%20Automated%22) +* Find an open issue labeled **"STATE : To Be Automated"** +* Select a scenario from the `Core` or `Modules` scope + +--- + +### 2. Setup your environment + +#### Prerequisites + +* Node.js (recommended LTS version) +* npm +* Git + +#### Project setup + +* Checkout your fork of PrestaShop on the `develop` branch +* Follow the [installation guide](https://devdocs.prestashop-project.org/9/basics/installation/) +* Install your shop with: + + * Language: **English** + * Country: **France** + +#### UI test setup + +```bash +cd tests/UI/ +npm install +cp .env.local .env +``` + +Update the `.env` file to match your local environment. Make sure to configure: + +* `BASE_URL` +* Browser settings +* Credentials if required + +#### Run a test + +You can run a specific E2E test using: + +```bash +TEST_PATH="functional/BO/00_login/02_login.ts" npm run test:specific:fast-fail +``` + +--- + +### 3. Create the test + +You can now start writing your test. + +* The directory structure mirrors the scenario structure +* Place your test in the corresponding folder +* Follow existing naming conventions + +#### Tech stack + +* **Mocha**: test framework +* **Playwright**: browser automation +* **@prestashop-core/ui-testing**: utilities and Page Object Models + +#### Guidelines + +* Follow the scenario strictly +* Use the Page Object Model pattern +* Reuse existing utilities and helpers +* Avoid hardcoded values +* Ensure your test is stable and deterministic + +--- + +### 4. Create the Pull Request + +Once your test runs successfully locally: + +* Push your branch +* Open a Pull Request targeting the `develop` branch +* Trigger a run from your fork of the GitHub Action `ga.tests.ui.pr` + +Make sure all checks pass before requesting a review. + +--- + +### 5. Review process + +The review is performed by [Software Developers in Test](/project-organization/people-and-roles/#software-developers-in-test). + +During the review, the following checks are performed: + +* Compliance with contribution guidelines +* CI status (lint, TypeScript checks, tests) +* Respect of the original scenario +* Test stability in CI +* Proper use of the Page Object Model pattern + +--- + +### 6. Merge + +The PR is merged after two approvals from [Software Developers in Test](/project-organization/people-and-roles/#software-developers-in-test), including at least one maintainer. + +Once merged, the test is executed nightly to ensure ongoing stability of the project: + +* [https://nightly.prestashop-project.org/](https://nightly.prestashop-project.org/) + +--- + +## Best practices + +* Keep tests independent +* Avoid shared state between tests +* Use Page Object Models consistently +* Prefer reusable helpers from `@prestashop-core/ui-testing` +* Keep tests readable and maintainable + +--- + +## Troubleshooting + +* Ensure your `.env` file is correctly configured +* Verify that your shop is properly installed +* Run tests in headed mode for debugging if needed +* Check CI logs if tests fail on the pipeline