From 854e10dd0507e0ea7a0381ff7d21982d53a856f6 Mon Sep 17 00:00:00 2001 From: cryptotavares Date: Fri, 19 Jul 2024 11:56:17 +0100 Subject: [PATCH] chore: reorganise test docs Created a test directory with an overview doc and docs with specific guidelines for each test type --- README.md | 6 +- docs/test-guidelines.md | 57 ------------------- docs/{ => testing}/e2e-testing.md | 0 .../e2e/extension-e2e-guidelines.md | 0 .../e2e/mobile-e2e-guidelines.md | 0 docs/testing/overview.md | 44 ++++++++++++++ docs/testing/ui-integration-testing.md | 27 +++++++++ docs/{ => testing}/unit-testing.md | 2 + 8 files changed, 77 insertions(+), 59 deletions(-) delete mode 100644 docs/test-guidelines.md rename docs/{ => testing}/e2e-testing.md (100%) rename docs/{ => testing}/e2e/extension-e2e-guidelines.md (100%) rename docs/{ => testing}/e2e/mobile-e2e-guidelines.md (100%) create mode 100644 docs/testing/overview.md create mode 100644 docs/testing/ui-integration-testing.md rename docs/{ => testing}/unit-testing.md (98%) diff --git a/README.md b/README.md index 3762e1d..4bfa831 100644 --- a/README.md +++ b/README.md @@ -12,5 +12,7 @@ This is a living repository — nothing is set in stone! If you're member of Met - [Secure Development Lifecycle Policy](./docs/sdlc.md) - [Secure Coding Guidelines](./docs/secure-coding-guidelines.md) - [TypeScript Guidelines](./docs/typescript.md) -- [Unit Testing Guidelines](./docs/unit-testing.md) -- [E2E Testing Guidelines](./docs/e2e-testing.md) +- [Testing Guidelines](./docs/testing/overview.md) + - [Unit Testing Guidelines](./docs/testing/unit-testing.md) + - [UI Integration Testing Guidelines](./docs/testing/ui-integration-testing.md) + - [E2E Testing Guidelines](./docs/testing/e2e-testing.md) diff --git a/docs/test-guidelines.md b/docs/test-guidelines.md deleted file mode 100644 index 29d3567..0000000 --- a/docs/test-guidelines.md +++ /dev/null @@ -1,57 +0,0 @@ -# Test guidelines - -At MetaMask, we are committed to delivering high-quality software. A key aspect of achieving this goal is through a robust testing strategy that includes both end-to-end (e2e), integration and unit tests. This document provides comprehensive guidelines on each testing type, emphasizing the importance of choosing the right test for the right scenario and detailing the specific practices for writing and organizing these tests. - -## What are unit tests? - -Unit tests understanding is a bit more diffuse. As there is no consensus on how they should be written and what they should test. But generically, [as captured by Martin Fowler](https://martinfowler.com/articles/2021-test-shapes.html), there's two lines of thought: solitary unit tests and sociable unit tests. Within MetaMask there are multiple examples from tests and discussions highlighting the two types (for example you can check the discussion on [this PR](https://www.google.com/url?q=https://github.com/MetaMask/core/pull/3827%23discussion_r1469377179&sa=D&source=editors&ust=1716475694980436&usg=AOvVaw3oTcfVgfRuiQFSDChZPrFM)) -Unit tests examine individual components or functions in isolation or within their immediate context. At MetaMask we encourage a flexible approach to unit testing, recognizing the spectrum between sociable and solitary unit tests. - -**When to write unit tests?** -All components, except page-level components, should be validated through unit tests. These tests focus on the component's internal logic and functionality. Integration tests are preferred for page-level components. However, developers may choose to write sociable unit tests for specific scenarios where integration tests might not be necessary or practical. - -**Generic guidelines** - -- **Flexibility in Isolation**: Depending on the test's purpose, developers can choose between sociable unit tests (without mocking child components) and solitary unit tests (with mocked dependencies) to best suit the testing needs. -- **Colocation**: Keep unit test files next to their corresponding implementation files. This practice enhances test discoverability and maintenance. -- **Granularity and Focus**: Ensure unit tests are focused and granular, targeting specific functionalities. The choice between sociable and solitary testing should be guided by the test's objectives and the component's role within the application. -- **Unit Tests for Page Components**: While integration tests are the primary method for testing page-level components, developers have the discretion to use unit tests for specific cases. This flexibility allows for targeted testing of component logic or behavior that may not require the full app context. -- **Best Practices**: Follow the [unit test best practices](./unit-testing.md). - -## What are integration tests? - -Integration tests evaluate the interaction between multiple components within the application, ensuring they work together as intended. For MetaMask, we are aiming to make UI integration tests particularly focused on page-level components and are conducted in the context of the full UI application. - -**When to write integration tests?** -Integration tests should be written for page-level components. These tests should simulate user journeys and validate the application's behavior in a full app context. - -**Generic guidelines** - -- **Full App Context**: Always test page-level components in the context of the full application. This approach ensures that tests reflect real user scenarios and interactions within the app. -- **Focus on User Journeys**: Design tests to mimic actual user actions and flows. This helps in identifying issues that could affect the user experience. -- **Avoid Testing Non-Page Components**: Integration tests should not be written for components other than page-level components. Other components should be tested using unit tests. -- **Avoid Snapshots**: Refrain from using snapshot testing in integration tests. They tend to be less meaningful in the context of full app testing and can lead to brittle tests. -- **Test Location**: Place integration test files within a `test/integration` directory. This centralized location helps manage tests that span multiple pages and components, improving maintenance and discoverability. This approach differs from unit tests, where co-location with the component is standard. -- **No Mocks**: Keep mocking to minimum. Ideally only the background connection, or any network request (fired from the UI) should be mocked. - -## What are e2e tests? - -e2e tests simulate real user scenarios from start to finish, testing the application as a whole. In the Extension, e2e tests are tests that strive to test a real extension app (including background, contentscript and ui processes) in a controlled environment from a user perspective. - -**When to write e2e tests?** -Testing application's integration with external systems or services through critical user journeys. This includes any interactions between the UI, background process, dapp, blockchain, etc. - -**Generic guidelines** - -- **Realistic Scenarios**: Test scenarios that closely mimic real user actions and flows. -- **Best Practices**: Follow the [e2e test best practices](./e2e-testing.md). - -## Broader guidelines - -- **Code fencing:** is very problematic for unit/integration testing. We should avoid it. -- **jest manual mocks:** This types of mocks are automatically picked up by jest for all tests. We should be very careful when writing this types of mocks as they will be shared across all tests. And with integration tests, as we are aiming to mock as little as possible, we should avoid this at all costs. - -## Conclusion - -To sum up, understanding the distinction between e2e, integration and unit tests and applying them appropriately is crucial for maintaining MetaMask's code quality and reliability. Integration tests offer a broad view of user interactions and system integration for page-level components, while unit tests provide detailed insights into the functionality of individual components,and e2e tests validate the application's overall behavior, ensuring readiness for production. -By following these guidelines, developers can ensure comprehensive test coverage, contributing to the robustness and user satisfaction of the application diff --git a/docs/e2e-testing.md b/docs/testing/e2e-testing.md similarity index 100% rename from docs/e2e-testing.md rename to docs/testing/e2e-testing.md diff --git a/docs/e2e/extension-e2e-guidelines.md b/docs/testing/e2e/extension-e2e-guidelines.md similarity index 100% rename from docs/e2e/extension-e2e-guidelines.md rename to docs/testing/e2e/extension-e2e-guidelines.md diff --git a/docs/e2e/mobile-e2e-guidelines.md b/docs/testing/e2e/mobile-e2e-guidelines.md similarity index 100% rename from docs/e2e/mobile-e2e-guidelines.md rename to docs/testing/e2e/mobile-e2e-guidelines.md diff --git a/docs/testing/overview.md b/docs/testing/overview.md new file mode 100644 index 0000000..1664c85 --- /dev/null +++ b/docs/testing/overview.md @@ -0,0 +1,44 @@ +# Testing Overview + +At MetaMask, we are committed to delivering high-quality software. A key aspect of achieving this goal is through a robust testing strategy that includes both end-to-end (e2e), integration and unit tests. This document provides comprehensive guidelines on each testing type, emphasizing the importance of choosing the right test for the right scenario and detailing the specific practices for writing and organizing these tests. + +## What are unit tests? + +Unit testing is a conceptually vague practice, as there is no consensus on how they should be written and what they should test. But in general, [as outlined by Martin Fowler](https://martinfowler.com/articles/2021-test-shapes.html), there two common approaches: solitary unit tests and sociable unit tests. At MetaMask, we employ both of these types of unit tests (see [discussion on the use cases of each type](https://github.com/MetaMask/core/pull/3827#discussion_r1469377179)) +Unit tests examine individual components or functions in isolation or within their immediate context. At MetaMask we encourage a flexible approach to unit testing, recognizing the spectrum between sociable and solitary unit tests. + +### When to write unit tests? + +All components or functions should be validated through unit tests. These tests focus on the component's or function's internal logic and functionality. +If UI Integration tests are available, those are preferred for page-level components. However, developers may choose to write sociable unit tests for specific scenarios where UI integration tests might not be necessary or practical. + +**Best Practices**: Follow the [unit test best practices](./unit-testing.md). + +## What are UI integration tests? + +UI integration tests evaluate the interaction between multiple components within the application, ensuring they work together as intended. For MetaMask, we are aiming to make UI integration tests particularly focused on page-level components and are conducted in the context of the full UI application. + +### When to write UI integration tests? + +UI integration tests should be written for page-level components. These tests should simulate user journeys and validate the application's behavior in a full app context. + +**Best Practices**: Follow the [ui integration tests best practices](./ui-integration-testing.md). + +## What are end-to-end tests? + +End-to-end tests simulate real user scenarios from start to finish, testing the application as a whole. In the Extension, end-to-end tests are tests that strive to test a real extension app (including background, contentscript and ui processes) in a controlled environment from a user perspective. + +### When to write end-to-end tests? + +Testing application's integration with external systems or services through critical user journeys. This includes any interactions between the UI, background process, dapp, blockchain, etc. End-to-end tests should closely mimic real user actions and flows. + +**Best Practices**: Follow the [end-to-end test best practices](./e2e-testing.md). + +## Generic testing considerations + +- **Code fencing:** Code fencing is available in MetaMask Extension and Mobile codebases. Though usefull for its purposes, this practice is very problematic for unit/UI integration testing. We should avoid it. + +## Conclusion + +To sum up, understanding the distinction between end-to-end, UI integration and unit tests and applying them appropriately is crucial for maintaining MetaMask's code quality and reliability. UI Integration tests offer a broad view of user interactions and system integration for page-level components, while unit tests provide detailed insights into the functionality of individual components, and end-to-end tests validate the application's overall behavior, ensuring readiness for production. +By following these guidelines, developers can ensure comprehensive test coverage, contributing to the robustness and user satisfaction of the application diff --git a/docs/testing/ui-integration-testing.md b/docs/testing/ui-integration-testing.md new file mode 100644 index 0000000..447ddb9 --- /dev/null +++ b/docs/testing/ui-integration-testing.md @@ -0,0 +1,27 @@ +# UI Integration Testing Guidelines + +## Use Jest + +Just like for unit tests, for UI integration tests, we use Jest as the test runner and testing framework. Jest provides a rich set of features that make it easy to write and maintain tests. UI integration tests should be written following the same conventions as unit tests. + +## Focus on User Journeys + +UI integration tests should focus on user journeys and interactions within the application. Design tests to mimic actual user actions and flows. This helps in identifying issues that could affect the user experience. + +### Full App Context + +Always test page-level components in the context of the full application. This approach ensures that tests reflect real user scenarios and interactions within the app. + +UI integration tests should not be written for components other than page-level components. Other components should be tested using unit tests. + +## Test Location + +Place integration test files within a `test/integration` directory. This centralized location helps manage tests that span multiple pages and components, improving maintenance and discoverability. This approach differs from unit tests, where co-location with the component is standard. + +## Avoid Snapshot testing + +Refrain from using snapshot testing in UI integration tests. They tend to be less meaningful in the context of full app testing and can lead to brittle tests. + +## No Mocking UI Components + +Keep mocking to minimum. Ideally only the background connection (MetaMask Extension), or any network request (fired from the UI) should be mocked. diff --git a/docs/unit-testing.md b/docs/testing/unit-testing.md similarity index 98% rename from docs/unit-testing.md rename to docs/testing/unit-testing.md index 035c98e..d16304c 100644 --- a/docs/unit-testing.md +++ b/docs/testing/unit-testing.md @@ -1070,3 +1070,5 @@ Jest incorporates most of the features of Sinon with a slimmer API: - `jest.fn()` can be used in place of `sinon.stub()`. - `jest.spyOn(object, method)` can be used in place of `sinon.spy(object, method)` or `sinon.stub(object, method)` (with the caveat that the method being spied upon will still be called by default). - `jest.useFakeTimers()` can be used in place of `sinon.useFakeTimers()` (though note that Jest's "clock" object had fewer features than Sinon's prior to Jest v29.5). + +**Avoid jest manual mocks:** According to jest `Manual mocks are defined by writing a module in a __mocks__/ subdirectory immediately`. These types of mocks are automatically picked up by jest for all tests. We should be very careful when writing this types of mocks as they will be shared across all tests. And with UI integration tests, as we are aiming to mock as little as possible, we should avoid this at all costs.