docs(e2e): contribution guidelines for e2e tests (#1896)

nilgaar · josephca · web-flow · commit a2cf29f89d0f · 2024-11-12T11:11:18.000Z
* style more like

* add anotation about running on CI

* expanding and grouping developer guidelines

* add paths ignore for e2e docs

* adding Use of External Sources for Validation

* reorganization

* delete innecessari duplications of principles for new PRs

* move e2e contributing file

* delete duplicates

* +readme.md

* relative paths on Update Documentation

---------

Co-authored-by: Joseph Kim &lt;joskim@redhat.com&gt;
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -6,79 +6,177 @@ We are excited to see you want to be a part of this project by contributing. Her
 
 ### Clone and Install
 
-1. For the repository here in GitHub
-2. Clone your forked version of the Showcase app
-3. Install dependencies using `yarn install`
-4. Run type generation and checks using `yarn tsc`
+```bash
+git clone https://github.com/your-username/backstage-showcase.git  # Clone your forked repository
+cd backstage-showcase                                              # Change to the project directory
+yarn install                                                       # Install dependencies
+yarn tsc                                                           # Run type generation and checks
+```
 
 ### Run the Showcase App
 
-We currently have quite a bit of moving parts for the showcase application. As such we have documentation dedicated to the requirements for running the showcase app under [getting-started.md](https://github.com/janus-idp/backstage-showcase/blob/main/showcase-docs/getting-started.md)
+We currently have quite a bit of moving parts for the showcase application. As such, we have documentation dedicated to the requirements for running the showcase app under [getting-started.md](https://github.com/janus-idp/backstage-showcase/blob/main/showcase-docs/getting-started.md).
+
+### Useful Scripts
 
-Some useful package scripts for the application
+Our project uses [Turborepo](https://turbo.build/repo) for running scripts across packages efficiently. Here are some useful scripts used in the project:
 
-```shell
-yarn start # Starts the application
-yarn tsc # Type generation and checks
-yarn test
-yarn test:e2e
-yarn lint # Lint packages
-yarn ci # Mirrors our CI in GitHub
-yarn prettier:check # Checks for formatting errors
-yarn prettier:fix # Fixes formatting errors
+```bash
+yarn start             # Starts the backend application
+yarn dev               # Starts both backend and frontend applications
+yarn build             # Builds all packages
+yarn tsc               # Runs TypeScript type checks across all packages
+yarn test              # Runs tests across all packages
+yarn lint:check        # Checks for linting errors across all packages
+yarn lint:fix          # Fixes linting errors automatically across all packages
+yarn prettier:check    # Checks for formatting issues across all packages
+yarn prettier:fix      # Fixes formatting issues automatically across all packages
+yarn clean             # Cleans up build artifacts across all packages
 ```
 
 ## Contributions
 
-We welcome code and non-code contributions to our project. Non-code contributions can come in the form of documentation updates, bug reports, enhancement and feature requests.
+We welcome code and non-code contributions to our project. Non-code contributions can come in the form of documentation updates, bug reports, enhancement requests, and feature requests.
+
+### Finding Issues to Work On
+
+Want to submit some changes to the code? The best place to start is to look through our issues for [bugs](https://github.com/janus-idp/backstage-showcase/issues?q=is%3Aopen+is%3Aissue+label%3Akind%2Fbug), [good first issues](https://github.com/janus-idp/backstage-showcase/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22), and [help wanted](https://github.com/janus-idp/backstage-showcase/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22). These are a great starting point for new contributors.
 
 ### Bug Reporting
 
-If you found a bug in our showcase app, please submit an [issue](https://github.com/janus-idp/backstage-showcase/issues/new?assignees=&labels=kind%2Fbug%2Cstatus%2Ftriage&template=bug.md) describing the problem that you ran into. Some important information to include are steps to reproduce the bug, the app-config.yaml that is being used, and any relevant logs. This will help us narrow down the potential cause of the bug and speed up the time it takes to solve the problem at hand.
+If you found a bug in our showcase app, please submit an [issue](https://github.com/janus-idp/backstage-showcase/issues/new?assignees=&labels=kind%2Fbug%2Cstatus%2Ftriage&template=bug.md) describing the problem that you ran into. Important information to include:
+
+- Steps to reproduce the bug
+- The `app-config.yaml` that is being used (**remember to remove all secrets before sharing**)
+- Any relevant logs
 
-**Please remember to remove all secrets from the app-config.yaml before sharing.**
+This will help us narrow down the potential cause of the bug and speed up the time it takes to solve the problem at hand.
 
 ### Updating Backstage Dependencies
 
-1. Run the following command
+To update Backstage dependencies, run the following command:
 
-   ```console
-   yarn versions:all
-   ```
+```bash
+yarn versions:bump     # Updates Backstage dependencies
+```
 
 ### Enhancement Requests
 
-Want an enhancement of a feature or workflow, you can submit an [issue](https://github.com/janus-idp/backstage-showcase/issues/new?assignees=&labels=kind%2Fenhancement%2Cstatus%2Ftriage&template=enhancement.md) describing the enhancement. Maybe you see a feature that we could provide a better experience to. This would be that opportunity to call it out. It is important to include in the issue what you are wanting to see improved, what the current behavior is, and what the new behavior you wish to see.
+If you want an enhancement of a feature or workflow, you can submit an [issue](https://github.com/janus-idp/backstage-showcase/issues/new?assignees=&labels=kind%2Fenhancement%2Cstatus%2Ftriage&template=enhancement.md) describing the enhancement. Include:
+
+- What you are wanting to see improved
+- The current behavior
+- The new behavior you wish to see
 
 ### Feature Requests
 
-Want to see a new feature within the showcase app, file an [issue](https://github.com/janus-idp/backstage-showcase/issues/new?assignees=&labels=kind%2Ffeature%2Cstatus%2Ftriage&template=feature.md) detailing the new feature. Sometimes we don't know about the latest and greatest and this issue is a great way for you to communicate that to us. Be sure to include information on what you are trying to achieve with the new issue, what you will need, who will have access, and any relevant documentation / information on the new feature.
+If you want to see a new feature within the showcase app, file an [issue](https://github.com/janus-idp/backstage-showcase/issues/new?assignees=&labels=kind%2Ffeature%2Cstatus%2Ftriage&template=feature.md) detailing the new feature. Include:
+
+- What you are trying to achieve with the new feature
+- What you will need
+- Who will have access
+- Any relevant documentation or information on the new feature
 
 ### Documentation
 
-Documentation is another option for contributing to us. If there is documentation that is unclear or could use some TLC, please raise an issue.
+Documentation is another option for contributing to us. If there is documentation that is unclear or could use some improvements, please raise an issue or submit a pull request.
 
 ### Pull Requests
 
-Want to submit some changes to the code? The best place to start is to look through our issues for [bugs](https://github.com/janus-idp/backstage-showcase/issues?q=is%3Aopen+is%3Aissue+label%3Akind%2Fbug), [good first issues](https://github.com/janus-idp/backstage-showcase/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22), and [help wanted](https://github.com/janus-idp/backstage-showcase/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22). Be sure to include a description of the changes made, which issue this PR will fix (if any), PR acceptance criteria, and any special notes to the reviewers.
+If you want to submit code changes to the project, here are some guidelines:
 
-Before submitting the PR, it is important to run some of our package scripts to ensure that the code changes will pass our CI workflow. These include running `yarn lint` `yarn prettier:write` `yarn test` `yarn test:e2e` and `yarn build`. This saves time from having to go back and make changes to your PR.
+1. **Create a Branch**
+
+   ```bash
+   git checkout -b your-feature-branch  # Create a new branch for your feature
+   ```
 
-A special note. If there will be changes to the [app config](https://github.com/janus-idp/backstage-showcase/blob/main/app-config.yaml), we ask that [documentation](https://github.com/janus-idp/backstage-showcase/blob/main/showcase-docs/getting-started.md) be updated if it will be a requirement for running the app. We also ask to ensure that the app will still work in the case of dummy information being supplied to the app config. While it is not a hard requirement, it does help others with quickly being able to get up and running with the showcase app.
+2. **Implement Your Changes**
 
-### Adding statically linked plugins for frontend and backend
+   Make your code changes, ensuring that you follow the project's coding standards and best practices.
+
+3. **Testing**
+
+   - **Run Tests:** Ensure all tests pass before committing.
+
+     ```bash
+     yarn test         # Run unit tests
+     cd e2e-tests
+     yarn showcase     # Run e2e tests
+     ```
+
+     _For more on the e2e, check the [e2e contributing guidelines](./docs/e2e-tests/CONTRIBUTING.MD)_
+
+   - **Note on Environment Dependencies:**
+
+     - If your new or edited code can't be validated locally due to environment dependencies, you can open a **draft Pull Request (PR)**. This allows the tests to run on the test environment as described in our CI documentation.
+
+4. **Linting and Formatting**
+
+   Ensure your code passes linting and formatting checks.
+
+   ```bash
+   yarn lint:check     # Checks for linting errors
+   yarn lint:fix       # Fixes linting errors automatically
+   yarn prettier:check # Checks for formatting issues
+   yarn prettier:fix   # Fixes formatting issues automatically
+   ```
 
-When contributing a new @internal plugin into this repo, you must remember to add the plugin to the Dockerfiles under the section titled `Stage 2 - Install dependencies`:
+5. **Ensure CI Passes**
+
+   Your contributions will need to pass the Continuous Integration (CI) tests for pull requests.
+
+6. **Commit Changes**
+
+   Use meaningful commit messages following the [Conventional Commits](https://www.conventionalcommits.org/) specification.
+
+   ```bash
+   git commit -m "feat: add new feature"  # Commit your changes with a meaningful message
+   ```
+
+7. **Update Documentation**
+
+   If there will be changes to the [app config](app-config.yaml), we ask that [documentation](README.md#getting-started) be updated if it will be a requirement for running the app. We also ask to ensure that the app will still work in the case of dummy information being supplied to the app config. While it is not a hard requirement, it does help others with quickly being able to get up and running with the showcase app.
+
+8. **Push to Your Fork**
+
+   ```bash
+   git push origin your-feature-branch    # Push your branch to your fork
+   ```
+
+9. **Open a Pull Request**
+
+   Go to the original repository and click on **New Pull Request**. Provide a clear description of your changes, including any issues your PR fixes, acceptance criteria, and any special notes to the reviewers.
+
+## Commit Messages
+
+Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
+
+- `feat`: A new feature.
+- `fix`: A bug fix.
+- `docs`: Documentation changes.
+- `style`: Code style changes (formatting, missing semi-colons, etc.).
+- `refactor`: Code changes that neither fix a bug nor add a feature.
+- `test`: Adding or correcting tests.
+- `chore`: Changes to the build process or auxiliary tools.
+
+### Adding Statically Linked Plugins for Frontend and Backend
+
+When contributing a new `@internal` plugin into this repo, you must remember to add the plugin to the Dockerfiles under the section titled `Stage 2 - Install dependencies`:
 
 - [Upstream Dockerfile](.rhdh/docker/Dockerfile)
 - [Downstream Dockerfile](docker/Dockerfile)
 
 For example:
 
-```
+```dockerfile
 COPY $EXTERNAL_SOURCE_NESTED/plugins/dynamic-plugins-info/package.json ./plugins/dynamic-plugins-info/package.json
 ```
 
 ## Support
 
-You can reach out to us in our [community slack channel](https://join.slack.com/t/janus-idp/shared_invite/zt-1pxtehxom-fCFtF9rRe3vFqUiFFeAkmg) if you run into any issues with setup, running, or testing the application. Members of the team and community can assist you with questions and concerns you might have. Even if you don't need help, please consider joining and being involved in our community.
+You can reach out to us in our [community Slack channel](https://join.slack.com/t/janus-idp/shared_invite/zt-1pxtehxom-fCFtF9rRe3vFqUiFFeAkmg) if you run into any issues with setup, running, or testing the application. Members of the team and community can assist you with questions and concerns you might have. Even if you don't need help, please consider joining and being involved in our community.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [Apache-2.0 License](https://github.com/janus-idp/backstage-showcase/blob/main/LICENSE).
diff --git a/docs/e2e-tests/CONTRIBUTING.MD b/docs/e2e-tests/CONTRIBUTING.MD
@@ -0,0 +1,77 @@
+# Contributing
+
+We are excited that you want to be a part of this project by contributing to the end-to-end tests. Here is some information on how to get started, as well as our requirements and guidelines to ensure a smooth contribution process.
+
+## Getting Started
+
+Before you begin, please ensure you have followed the general setup instructions in the main [Contributing Guide](../../CONTRIBUTING.md) to clone the repository and install dependencies.
+**The [Readme](README.md) file contains practical information about the e2e project**
+
+## Contribution Guidelines
+
+We welcome both code and non-code contributions to our project. Non-code contributions can come in the form of documentation updates, enhancement requests, and new test requests.
+
+### Developer Guidelines
+
+These principles are valid for new contributions. Some parts of the codebase may not adhere yet to these principles, but improvements should be made in that direction.
+
+#### Architectural Principles
+
+1. **Naming Convention**
+
+   A naming convention is enforced for all entities, including variables, functions, and file names. Consistent naming ensures code clarity, maintainability, and ease of navigation throughout the project.
+
+2. **Code Visibility**
+
+   Carefully consider the visibility of all classes, variables, and functions. Exposed elements should be simple and understandable on the frontend while being versatile and resilient in the background. This promotes a clean and user-friendly API while maintaining robust internal functionality.
+
+3. **Test Isolation**
+
+   All tests should be written to be as isolated as possible. Even if current constraints (such as GitHub login rate limits) prevent complete independence, strive for maximum isolation. This approach ensures that when blockers are removed, refactoring can proceed smoothly.
+
+4. **Control Over Test Environment**
+
+   The test framework must have full control over the test environment. All environment configurations should be managed and propagated up to the Node.js layer, when possible. This ensures that the test environtment can be set up in case-to-case bases.
+
+5. **Team Agreement on Architecture Principles**
+
+   All architecture principles and guidelines must be agreed upon by the team. Every team member's voice is important, and open communication ensures alignment and shared understanding of the project's direction.
+
+#### Technical Guidelines
+
+1. **Page Object Model (POM)**
+
+   The Page Object Model (POM) design pattern is required for all test code. Until we find a better-suited standard, we adhere to this well-known and well-tested pattern to promote code reusability and maintainability.
+
+2. **Playwright Best Practices**
+
+   We follow Playwright best practices, including the use of fixtures. Adhering to these practices ensures that our tests are reliable, efficient, and maintainable. Please refer to the [Playwright Best Practices](https://playwright.dev/docs/best-practices) and [Fixtures](https://playwright.dev/docs/test-fixtures) documentation for guidance.
+
+3. **Avoid Using `uiHelper` in Spec Files**
+
+   - The `uiHelper` utility should not be used directly in spec files. The reason for that is that some methods in this class are too generic and sometimes it is difficult to point what they are intended. Idellay, they shall be called from inside a POM that states what thay are looking for.
+   - Use `uiHelper` methods only within the Page Object Model (POM) classes.
+   - When working with tests that directly use `uiHelper` in spec files, refactor them to move `uiHelper` usage into POM classes.
+   - This ensures that all UI interactions are encapsulated within page objects, promoting cleaner and more maintainable test code.
+
+4. **Use External Sources for Validation**
+
+   - **Avoid Hardcoded Data in Tests**
+
+     - When validating frontend results in your end-to-end tests, use external sources of truth such as APIs or databases instead of hardcoded information.
+     - This approach ensures that tests are more robust and accurately reflect the dynamic nature of the application data.
+
+### Adding New Tests
+
+When contributing new tests or modifying existing ones, please adhere to the guidelines.
+To open a PR, follow the steps described in the [general contribution guide](../../CONTRIBUTING.md)
+
+### Collaboration and Communication
+
+- **Team Consensus:**
+
+  - Engage with the team when introducing significant changes. Ensure that architectural decisions are agreed upon collectively.
+
+- **Open Communication:**
+
+  - Encourage discussion and feedback. All voices are important in shaping the project's direction.
diff --git a/docs/e2e-tests/README.md b/docs/e2e-tests/README.md
