chore(tests): Improve E2E Documentation #16909
Conversation
WalkthroughThe pull request includes significant updates to the documentation of the E2E Testing Library. Changes include a new title, refined section headers, and a restructured usage guide. The documentation now emphasizes shared configurations and multi-environment testing support. Additionally, the Mockoon usage guide has been clarified, and the troubleshooting section has been expanded to address common issues. Overall, the modifications aim to enhance clarity and organization for better usability. Changes
Possibly related PRs
Suggested labels
Suggested reviewers
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
Documentation and Community
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Outside diff range and nitpick comments (4)
libs/testing/e2e/README.md (4)
7-11: Enhance visual consistency in Contents sectionConsider using consistent emoji placement in the Contents section headers to match the document's style:
### Contents -• **🔧 Helper Functions**: Utility functions to simplify and standardize E2E testing across apps. -• **⚙️ Shared Playwright Configuration**: A common configuration used as the base for all app-specific Playwright configurations. -• **🌍 Multi-Environment Testing**: Support for running tests in `local`, `dev`, `staging`, and `prod` environments. +• **Helper Functions** 🔧: Utility functions to simplify and standardize E2E testing across apps. +• **Shared Playwright Configuration** ⚙️: A common configuration used as the base for all app-specific Playwright configurations. +• **Multi-Environment Testing** 🌍: Support for running tests in `local`, `dev`, `staging`, and `prod` environments.
49-85: Improve command descriptions readabilityConsider varying the sentence structure to avoid repetitive beginnings and make the documentation more engaging:
-• **Run with UI Mode**: Launch the tests with a UI to select and debug tests interactively. -• **Run Tests Without Caching**: Ensure a fresh run of tests without using cached results. -• **Run a Specific Project**: Run only the tests defined under a specific project in your Playwright config: -• **View the Test Report**: After running tests, use this command to view the generated report: -• **Run Specific Tests**: Use `--grep` to run tests matching a specific pattern: -• **Debug Mode**: Run tests in debug mode for better visibility: +• **UI Mode** 🖥️: Launch tests with an interactive UI for selection and debugging. +• **Fresh Run** 🔄: Execute tests without using cached results. +• **Project Selection** 📂: Execute tests from specific projects in your Playwright config: +• **Report Viewer** 📊: Display the generated test report. +• **Pattern Matching** 🔍: Execute tests matching specific patterns using `--grep`. +• **Debugging** 🐛: Enable debug mode for enhanced visibility during test execution.🧰 Tools
🪛 LanguageTool
[style] ~61-~61: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...e --skip-nx-cache ``` - Run a Specific Project: Run only the test...(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
95-96: Fix grammatical issues in the writing guideApply these corrections to improve readability:
-You should therefore aim to write test for: +You should therefore aim to write a test for: -Each test case (`test`) should test a specific scenario from end-to-end. If your test is getting long and complicated consider breaking it up within a `test` with `test.step` +Each test case (`test`) should test a specific scenario from end-to-end. If your test is getting long and complicated, consider breaking it up within a `test` with `test.step`Also applies to: 142-143
🧰 Tools
🪛 LanguageTool
[uncategorized] ~95-~95: Possible missing article found.
Context: ...ses. You should therefore aim to write test for: - Most common usage patterns - Us...(AI_HYDRA_LEO_MISSING_A)
197-197: Standardize placeholder formatFor consistency with other placeholders in the documentation, update the port placeholder:
-yarn mockoon-cli start --data ./apps/<app>/e2e/mocks/<app-mock>.json --port <port> +yarn mockoon-cli start --data ./apps/<app>/e2e/mocks/<app-mock>.json --port <port-number>
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
📒 Files selected for processing (1)
libs/testing/e2e/README.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
libs/testing/e2e/README.md (1)
Pattern libs/**/*: "Confirm that the code adheres to the following:
- Reusability of components and hooks across different NextJS apps.
- TypeScript usage for defining props and exporting types.
- Effective tree-shaking and bundling practices."
🪛 LanguageTool
libs/testing/e2e/README.md
[style] ~61-~61: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...e --skip-nx-cache ``` - Run a Specific Project: Run only the test...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[uncategorized] ~95-~95: Possible missing article found.
Context: ...ses. You should therefore aim to write test for: - Most common usage patterns - Us...
(AI_HYDRA_LEO_MISSING_A)
[uncategorized] ~142-~142: Possible missing comma found.
Context: ...o-end. If your test is getting long and complicated consider breaking it up within a test...
(AI_HYDRA_LEO_MISSING_COMMA)
[style] ~142-~142: ‘in succession’ might be wordy. Consider a shorter alternative.
Context: ...twithtest.step`; each step will run in succession and the failure/success report is easie...
(EN_WORDINESS_PREMIUM_IN_SUCCESSION)
[typographical] ~166-~166: It appears that a comma is missing.
Context: ...ter the basic page has loaded. In such cases you can wait for the elements to exist ...
(DURING_THAT_TIME_COMMA)
🔇 Additional comments (1)
libs/testing/e2e/README.md (1)
200-215: LGTM! Well-organized troubleshooting section
The troubleshooting section is comprehensive and well-structured, with clear error descriptions and solutions.
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (5)
libs/testing/e2e/README.md (5)
30-34: Add parameter documentation for configuration optionsConsider adding JSDoc comments to document the expected parameters in the configuration example:
const playwrightConfig = createPlaywrightConfig({ + /** URL where the web server will be started for testing */ webServerUrl: '<web-server-url>', + /** Command to start the web server */ command: '<command>', // Add any app-specific configurations here })
41-45: Enhance command structure explanationTo improve readability and avoid repetition, consider restructuring the command explanation:
-Use the following command structure to run tests for any app: - -```bash -yarn e2e <app-name> -``` +The base command structure for running tests is: + +```bash +yarn e2e <app-name> [options] +``` + +Where `[options]` can be any of the flags described below.
142-143: Fix grammatical issues in test descriptionThe sentence structure needs improvement:
-Each test case (`test`) should test a specific scenario from end-to-end. If your test is getting long and complicated consider breaking it up within a `test` with `test.step`; each step will run in succession and the failure/success report is easier to read. +Each test case (`test`) should test a specific scenario from end-to-end. If your test is getting long and complicated, consider breaking it up within a `test` with `test.step`. Each step will run sequentially, making the failure/success report easier to read.🧰 Tools
🪛 LanguageTool
[uncategorized] ~142-~142: Possible missing comma found.
Context: ...o-end. If your test is getting long and complicated consider breaking it up within atest...(AI_HYDRA_LEO_MISSING_COMMA)
[style] ~142-~142: ‘in succession’ might be wordy. Consider a shorter alternative.
Context: ...twithtest.step`; each step will run in succession and the failure/success report is easie...(EN_WORDINESS_PREMIUM_IN_SUCCESSION)
192-197: Add environment variable configuration noteConsider adding information about environment variables that might be needed for the mock server:
### 🖥️ Running Mockoon Server with CLI To start a mock server: ```bash yarn mockoon-cli start --data ./apps/<app>/e2e/mocks/<app-mock>.json --port <port>
+Note: You may need to configure environment variables in your mock file for different testing environments (local, staging, etc.).
--- `202-206`: **Enhance error categorization** Consider categorizing errors by their source/type for better navigation: ```diff -### 🔄 Common Issues +### 🔄 Common Issues by Category + +#### Network Issues +- **💀 ESOCKETTIMEDOUT**: Likely an infrastructure issue. Reach out to DevOps if persistent. + +#### Server Issues +- **500: Internal Server Error**: If not related to your code, contact the DevOps team.
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
📒 Files selected for processing (1)
libs/testing/e2e/README.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
libs/testing/e2e/README.md (1)
Pattern libs/**/*: "Confirm that the code adheres to the following:
- Reusability of components and hooks across different NextJS apps.
- TypeScript usage for defining props and exporting types.
- Effective tree-shaking and bundling practices."
🪛 LanguageTool
libs/testing/e2e/README.md
[style] ~61-~61: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...e --skip-nx-cache ``` - Run a Specific Project: Run only the test...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[uncategorized] ~142-~142: Possible missing comma found.
Context: ...o-end. If your test is getting long and complicated consider breaking it up within a test...
(AI_HYDRA_LEO_MISSING_COMMA)
[style] ~142-~142: ‘in succession’ might be wordy. Consider a shorter alternative.
Context: ...twithtest.step`; each step will run in succession and the failure/success report is easie...
(EN_WORDINESS_PREMIUM_IN_SUCCESSION)
[typographical] ~166-~166: It appears that a comma is missing.
Context: ...ter the basic page has loaded. In such cases you can wait for the elements to exist ...
(DURING_THAT_TIME_COMMA)
🔇 Additional comments (1)
libs/testing/e2e/README.md (1)
1-11: Well-structured introduction and overview!
The introduction and overview sections are clear, well-organized, and effectively use emojis for visual separation of sections.
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #16909 +/- ##
=======================================
Coverage 36.46% 36.46%
=======================================
Files 6903 6903
Lines 144575 144575
Branches 41282 41282
=======================================
Hits 52715 52715
Misses 91860 91860
Flags with carried forward coverage won't be shown. Click here to find out more. Continue to review full report in Codecov by Sentry.
|
* chore(tests): Improve E2E Documentation * Update libs/testing/e2e/README.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --------- Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
Summary by CodeRabbit