#5341 code analysis documentation

docs/source/contributing/acceptance-tests.md

@@ -7,80 +7,115 @@ myst:
     "keywords": "Volto, Plone, frontend, React, helper command, redux, acceptance, tests, Cypress"
 ---
 
-# Acceptance testing
+# Acceptance tests
 
-Volto uses [Cypress](https://www.cypress.io/) for browser-based acceptance testing.
+Volto uses [Cypress](https://www.cypress.io/) for browser-based acceptance tests.
 
-There are a number of fixtures available covering all the configuration use cases.
-These fixtures have both a specific backend and frontend configuration setup and a related set of tests.
-The CI infrastructure runs them all automatically on every push to a branch or PR.
+There are a number of tests available covering all the configuration use cases.
+These tests have both a specific backend and frontend configuration setup and a related set of tests.
+The continuous integration infrastructure runs them all automatically on every push to a branch or a pull request.
 
 The tests can be run in headless mode (same as the CI does), or within the Cypress user interface.
 The latter is the one that you run under development.
 
+
 ## How to run acceptance tests locally (during development)
 
 When writing new acceptance tests, you usually want to minimize the time it takes to run the tests, while also being able to debug or inspect what's going on.
 
 Being able to restart individual components also comes in handy.
 It's recommended to start three individual terminal sessions, one each for running the Plone backend, the Volto frontend, and the acceptance tests.
+All sessions should start from the `packages/volto` directory.
 
-1.  Run the backend fixture.
+1.  In the first session, start the backend server.
 
     ```shell
     make start-test-acceptance-server
     ```
 
-2.  Run the frontend fixture.
+1.  In the second session, start the frontend server.
 
     ```shell
     make start-test-acceptance-frontend-dev
     ```
 
-3.  Run the Cypress tests for that fixture.
+1.  In the third session, start the Cypress tests runner.
 
     ```shell
     make test-acceptance
     ```
 
-Available fixtures:
+1.  In the Cypress pop-up test style, choose `E2E Testing`, since Volto's tests are end-to-end tests.
+
+1.  In the next section, select the browser you want Cypress to run in.
+    Although the core tests use `headless Electron` by default, you can choose your preferred browser for the tests development.
+
+1.  In the main Cypress runner section, you will see all of the test specs that Volto developers have written to test Volto and its packages.
+
+1.  To run a test, interact with the file based tree that displays all possible tests to run, and click on the test spec you need to run. 
 
-- Core (`core` or not special naming in the test commands)
-- Multilingual (`multilingual`)
-- Working Copy (`workingCopy`)
-- Core Sandbox (`coresandbox`)
+We provide the following major test specs:
 
-There are convenience commands for each of these fixtures. See `Makefile` for more information.
+-   Core (`core` used to test the core functionality of Volto)
+-   Multilingual (`multilingual` tests the multilingual support of Volto)
+-   Working Copy (`workingCopy` tests the working copy feature of Volto)
+-   Core Sandbox (`coresandbox` tests Volto using configuration and elements that are not present in vanilla Volto)
 
-### Writing new acceptance tests
+There are convenience commands for each of these specs.
+See `Makefile` at the root of the repository for more information.
 
-Go to the `cypress/tests` folder to see existing tests.
-There is a directory per fixture.
+
+### Write new acceptance tests
+
+Go to the folder `packages/volto/cypress/tests` to see existing tests.
+There is a directory per spec.
 This directory is hot reloaded with your changes as you write the tests.
-For more information on how to write Cypress tests:
 
-    https://docs.cypress.io
+```{seealso}
+[Cypress documentation](https://docs.cypress.io/guides/overview/why-cypress)
+```
 
 
 ## Helper commands
 
-There are some artifacts available for the acceptance tests made accessible to Cypress.
+There are some helper commands in {file}`packages/volto/cypress/support/commands.js` written by Volto contributors and made available for the acceptance tests using Cypress.
+
+Volto core makes heavy use of these helpers in the core tests to avoid verbose duplication, and they can make your life easier.
+Example of commands used in tests:
+
+```js
+  beforeEach(() => {
+    cy.autologin();
+    cy.createContent({
+      contentType: 'Document',
+      contentId: 'my-page-1',
+      contentTitle: 'My Page-1',
+      allow_discussion: true,
+    });
+    cy.visit('/contents');
+  });
+```
+
+`cy.autologin` and `cy.createContent` are commands that will auto login, then create the entered content before each test will run.
+This makes it easier to focus on the `act` and `assert` actions of the tests that make use of this test hook.
 
-### Access History, Redux Store and Settings
 
-We expose the History, {term}`Redux` Store and Settings from the app (only for Cypress environments) so we can easily access them and execute actions (like navigate using the router), dispatch Redux actions or change app settings "on the fly".
+### Access history, Redux store, and settings
 
-#### Navigate using React Router
+We expose the history, {term}`Redux` store, and settings from the app (only for Cypress environments) so we can easily access them and execute actions (like navigate using the router), dispatch Redux actions, or change app settings "on the fly".
 
-You can navigate using the React Router (ie. not reloading the page) with this command:
+#### Navigate using React router
+
+You can navigate using the React router without reloading the page with the following command:
 
 ```js
 cy.navigate('/events');
 ```
 
-#### Redux Store
 
-You can access the Redux store and check for specific states and dispatch actions by:
+#### Redux store
+
+You can access the Redux store and check for specific states and dispatch actions as shown:
 
 ```js
 import { updateIntl } from 'react-intl-redux';
@@ -100,11 +135,14 @@ dispatch(
 );
 ```
 
-More information about this: https://www.cypress.io/blog/2018/11/14/testing-redux-store/
+```{seealso}
+[Testing Redux Store](https://www.cypress.io/blog/2018/11/14/testing-redux-store/)
+```
+
 
 #### Volto settings
 
-You can modify on the fly the main Volto settings like this:
+You can modify the main Volto settings on the fly.
 
 ```js
 cy.settings().then(settings => {

docs/source/contributing/developing-core.md

@@ -252,6 +252,14 @@ pnpm start
 
 You can also run commands of specific workspaces using the `--filter` feature as shown in the previous section.
 
+```{note}
+If you make commits and you push to GitHub take advantage of the automatic continuous integration testing and check the `details` link for the checks that have failed if you get a failure.
+
+If the failure is simple and you understand it from start then it's enough to make a commit with the fix.
+
+If the failure is more complex consider running the linting and tests locally until you get no failures. Check the {ref}`linting`, {ref}`testing` and {ref}`acceptance-test` docs for more info on how todo that.
+```
+
 
 ## Developing other libraries
 

docs/source/contributing/linting.md

@@ -9,17 +9,12 @@ myst:
 
 # Linting
 
-```{note}
-This documentation is a work in progress. Any help is welcome to fill in the
-gaps!
-```
-
 Volto developers can enjoy a lot of freedom in their choice of text editors and
 IDEs, thanks to the strong tooling provided by the JavaScript ecosystem.
 
-At the core of these capabilities is ESLint, the advanced JavaScript linting
-and formatting tool. Also included with Volto is integration with Stylelint and
-Prettier.
+At the core of these capabilities is `ESLint`, the advanced JavaScript linting
+and formatting tool. Also included with Volto is integration with `Stylelint` and
+`Prettier`.
 
 For Visual Studio Code you'll need to integrate an
 [ESLint plugin](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint).
@@ -35,3 +30,60 @@ most importantly for .js/jsx files:
 - The editor should automatically flag unused imports
 - The editor should automatically (and properly) flag imported modules that are not found
 - The editor should provide automatic code formatting on save
+
+## Linting Volto core
+If you want to contribute to Volto core you need to perform several quality control tasks in order to ensure that you commits are not breaking the automated tests that Volto is performing on every commit.
+
+The first step in the testing hierarchy is the performing of code linting.
+
+Volto core should already perform these linting commands when commiting locally from the [husky](https://typicode.github.io/husky/get-started.html) integration, however if the the automated check doesn't happen when performing a commit or you want to get less information you can also run each linting task manually as you will learn how-to from the next section.
+
+If you want to see exactly which linting commands are set to run after a commit have a look at the [.lintstagedrc](https://github.com/plone/volto/blob/main/.lintstagedrc) file from the Volto project [main](https://github.com/plone/volto/) GitHub branch.
+
+Volto core performs linting using the following commands:
+- eslint - For finding problems in the project's code files
+- prettier - For uniform code formatting
+- stylelint - For uniform style formatting
+
+Although we can run the linting commands from the root of the project
+it will be easier to run the commands only for Volto core within the Volto core folder:
+
+  ```shell
+    cd packages/volto
+  ```
+
+From here we will have access to the commands to check for errors and to fix them as well, and we will go through all of the previously enumerated commands in the following section
+
+### Eslint, Prettier and Stylint
+
+You can run the `eslint`, `prettier` and `stylelint` commands by running the following from the Volto package folder:
+
+```shell
+  pnpm lint 
+  pnpm prettier
+  pnpm stylelint
+```
+
+If we get any errors some of them can be solved automatically by running `"lint-command":fix`:
+
+```shell
+  pnpm lint:fix
+  pnpm prettier:fix
+  pnpm stylelint:fix
+```
+
+> **Note**:
+The same commands can be found also in your Volto add-on projects as seen in the [package.json.tpl](https://github.com/plone/volto/blob/main/packages/generator-volto/generators/app/templates/package.json.tpl#L10) file.
+>
+> You will use similar commands to run the linting commands using `yarn`:
+
+```shell
+  yarn lint
+  yarn lint:fix
+  yarn prettier
+  yarn prettier:fix
+  yarn stylelint
+  yarn stylelint:fix
+```
+
+If the fix commands cannot fix the errors given by the linting commands you will need to fix the errors manually otherwise the commit will fail the testing infrastructure. If that happens your contribution will not be able to be merged until the pull request has every test passing.

docs/source/contributing/testing.md

@@ -17,12 +17,40 @@ mandatory in Volto core.
 
 Jest is configured in `package.json`, under the "jest" key.
 
+## Run Jest tests on Volto core
+Volto core is running the jest test using the `CI=true` option which will run all tests and display any errors found.
+
+While that is useful for the CI testing, Jest has several modes to run such as running in watch mode or running only failed tests or running specific tests only.
+
+To get to the test runner modes choice the easiest is to simply run `pnpm test`:
+```shell
+  pnpm test
+```
+Then you can follow the Jest promps for keys that you can enter in order to trigger the running of test, here are a few examples:
+```shell
+Watch Usage
+> Press a to run all tests.
+> Press f to run only failed tests.
+> Press q to quit watch mode.
+```
+
+You can also run only specific tests using the following commands:
+```shell
+  cd packages/volto
+  pnpm test src/components/theme/Image
+  # will run only the Image components tests
+```
+If you know you have a certain test that fails running that test only in watch
+mode makes it easier to test any code changes made if it fixed the code or not.
+
 ## Jest configuration override
 
 In CI or for testing addons, it's interesting to provide an alternate Jest configuration
 or slightly modify it. Volto provide a way to do it using a `jest.config.js` file or
 pointing the test runner to a file of your choice, using `RAZZLE_JEST_CONFIG`
 environment variable.
+Because the Volto add-ons and Volto add-ons projects are still using `yarn` you will
+run the test command using `yarn` instead of `pnpm` as used by Volto core.
 
 ```shell
 RAZZLE_JEST_CONFIG=my-custom-jest-config.js yarn test

packages/volto/news/5341.documentation

@@ -0,0 +1 @@
+Updated testing and code quality with information on how to contribute to Volto core. @ichim-david