doc(showcase): add a readme to explain how to update the screenshots …

…for visual testing (#2489)

## Proposed change

<!--
Please include a summary of the changes and the related issue.
Please also include relevant motivation and context.
-->

## Related issues

<!--
Please make sure to follow the [contribution
guidelines](https://github.com/amadeus-digital/Otter/blob/main/CONTRIBUTING.md)
-->

*- No issue associated -*

<!-- * 🐛 Fix #issue -->
<!-- * 🐛 Fix resolves #issue -->
<!-- * 🚀 Feature #issue -->
<!-- * 🚀 Feature resolves #issue -->
<!-- *  Pull Request #issue -->

.github/markdown-external-links.config.json

@@ -8,6 +8,9 @@
     },
     {
       "pattern": "https://img.shields.io/bundlephobia/*"
+    },
+    {
+      "pattern": "^https?://(127.0.0.1|localhost)[:/].*"
     }
   ],
   "replacementPatterns": [

.github/markdown-links.config.json

@@ -2,6 +2,9 @@
   "ignorePatterns": [
     {
       "pattern": "^https?:\/\/.*"
+    },
+    {
+      "pattern": "^https?://(127.0.0.1|localhost)[:/].*"
     }
   ],
   "replacementPatterns": [

CONTRIBUTING.md

@@ -21,7 +21,7 @@ The issue creation template requires:
 - NodeJS version
 - a fix suggestion, if possible
 
-If you already have a fix for the problem don't hesitate to [open a pull request](#creating-a-pull-request). Each pull request should be assign to an issue, so please create the issue and link it to the PR.
+If you already have a fix for the problem don't hesitate to [open a pull request](#creating-a-pull-request). Each pull request should be assigned to an issue, so please create the issue and link it to the PR.
 
 ## Creating a pull request
 
@@ -53,6 +53,7 @@ When contributing, please keep in mind the following rules:
 - A description comment must use the pattern `/** [Your comment] */`
 - Linter tasks must pass
 - Add relevant Unit Tests
+- E2E tests must pass (check [how to update screenshots for visual testing](./apps/showcase/scripts/update-screenshots/readme.md))
 - Any change should be followed by changes in the generator whenever it's applicable
 - Properties should have the most restricted type possible
 
@@ -72,12 +73,12 @@ To be able to benefit from this feature, you will need to perform the following
 
 1. Create an account on [Nx Cloud App](https://cloud.nx.app/)
 2. Create a Personal Access Token on [profile page](https://cloud.nx.app/profile/tokens).
-3. Follow [Nx Cloud instruction](https://nx.dev/ci/recipes/security/personal-access-tokens) to setup your previously generated PAT.
+3. Follow [Nx Cloud instruction](https://nx.dev/ci/recipes/security/personal-access-tokens) to set up your previously generated PAT.
 
 When building (`yarn build`) the project on the `main` branch (or another `release/*` branch), the remote cache will be downloaded.
 
 > [!NOTE]
-> Only Otter Team members can write Remote Cache on Nx Cloud, logged in user will be able to use Remote Cache in readonly access.
+> Only Otter Team members can write Remote Cache on Nx Cloud, logged-in users will be able to use Remote Cache in readonly mode.
 > The Local Cache is available for all users (logged or not to Nx Cloud).
 
 ### DevTools to create new Otter monorepo elements
@@ -103,6 +104,6 @@ As a reviewer, please follow these guidelines:
 - Always stay polite and professional in your comments.
 - The purpose of comments is to suggest improvements, ask a question or request for a change.
 - Comments should be constructive and suggest ways to improve things.
-- `Request changes` option should't be used if the comments consist only of questions.
+- `Request changes` option shouldn't be used if the comments consist only of questions.
 
 Thanks in advance for your contribution, and we look forward to hearing from you :)

apps/showcase/scripts/update-screenshots/readme.md

@@ -0,0 +1,14 @@
+# How to generate screenshots for the visual testing
+
+To minimize discrepancies on the screenshots between different operating systems, we are generating the screenshots from inside a docker.
+The procedure is the following:
+
+1. Prerequisite: you need a docker setup (or podman), `docker` should be available globally
+2. Build your application with your latest modifications `yarn nx build showcase`.
+3. Serve the application on port 8080 `npx http-server ./apps/showcase/dist/browser`\
+     The script will look on all local interfaces for an app running on `http://localhost:8080`
+4. Make sure all your changes on the spec files are commited `git commit`\
+     The project is cloned inside the docker image using `git clone` to avoid polluting the original folder.\
+     Only the screenshots are exported.
+5. Run the script to launch the e2e-tests inside the docker image `yarn workspace @o3r/showcase run update-screenshots`
+6. You should now have the updated screenshots in your project.