add adr for review

docs/ADR 001 Why Selenium Java.md

@@ -0,0 +1,79 @@
+ADR 001: Why Selenium Java?
+
+Date: 2024-09-12
+
+Status: Approved
+
+
+## Context
+- We need to build framework to test all Linagora products.
+
+## Problem
+- The team behind this framework is about 2 or 3 SDET.
+- We don't know how complex the eco will become in feature.
+
+## Options
+
+### Playwright
+1. Pros:
+* Cross-browser support: Runs on Chrome, Firefox, and WebKit (Safari) with a single API.
+* Multi-language support: Includes JavaScript, Python, C#, and Java.
+* Auto-waiting mechanism: Reduces flaky tests by waiting for elements to be ready.
+* Browser context isolation: Allows parallel test execution without interference.
+* Headless and headful execution: Suitable for both speed and debugging.
+* Network mocking and interception: Easy to simulate network conditions and application behavior.
+* Device emulation: Supports mobile device emulation and responsive design testing.
+* Detailed tracing and debugging: Provides video, screenshots, and trace files for troubleshooting.
+
+2. Cons:
+* Smaller community and ecosystem: Fewer tutorials and third-party tools compared to Selenium or Cypress.
+* Resource-intensive: Running multiple browser contexts or tests can consume significant resources.
+* Limited real-device support: Only emulates mobile devices, no support for actual devices.
+* Challenging integration with Selenium Grid: Requires additional setup for distributed testing.
+* Limited support for older browsers: Not ideal for testing on outdated browsers like Internet Explorer.
+
+
+### Cypress
+1. Pros:
+* Easy setup and use: Cypress is straightforward to install and configure, with a user-friendly API.
+* Real-time browser preview: Provides a real-time view of test execution, which helps in debugging.
+* Automatic waiting: Handles asynchronous operations and waits for elements automatically, reducing flaky tests.
+* Built-in assertion library: Includes built-in assertions, reducing the need for additional libraries.
+* Time-travel debugging: Allows you to inspect the state of your application at each step of the test.
+* Network stubbing: Easily mock and intercept network requests for more controlled testing environments.
+* Comprehensive documentation: Offers extensive documentation and examples to help with testing setup and best practices.
+
+2. Cons:
+* Limited browser support: Primarily supports Chrome and Chromium-based browsers, with limited support for Firefox and no support for Safari.
+* No support for multiple tabs or windows: Cannot handle tests that require interaction across multiple tabs or browser windows.
+* Resource-intensive: Can consume significant system resources, especially with a large number of tests or complex scenarios.
+* Not ideal for legacy browsers: Lacks support for older browsers like Internet Explorer.
+* Limited to JavaScript: Focuses solely on JavaScript, so it's not suitable for projects using other languages.
+
+### Selenium
+1. Pros:
+* Broad browser support: Selenium works with major browsers like Chrome, Firefox, Safari, and Edge, allowing cross-browser testing.
+* Tool integration: It integrates well with TestNG, JUnit, Cucumber, and Maven, creating a complete test framework.
+* Large community: Selenium has extensive documentation and a large support community.
+* Rich libraries: Offers robust libraries for interacting with web UI components.
+* Scalability: Easily extendable for complex testing like performance (JMeter), API (RestAssured), and mobile (Appium).
+* Flexibility: Supports various test levels (UI, integration, unit) and integrates smoothly with CI/CD pipelines.
+* Remote control: Selenium Grid allows remote browser control and parallel testing across environments.
+
+2. Cons:
+* Complex setup: Requires more configuration and setup compared to Cypress or Playwright.
+* Slower execution: Can be slower due to the need for WebDriver interactions and communication.
+* Flaky tests: More prone to flaky tests compared to Playwright and Cypress due to timing issues.
+* Limited real-time feedback: Doesn’t offer real-time test previews or time-travel debugging.
+
+## Decision
+
+We choose selenium because:
+- It is the most powerful tool. If we only have a small product, Selenium may be too powerful to use, but we are big.
+- We need it in Java because our developers feel comfortable with it. The dev team and QA team will work together on this framework.
+
+We not choose playright and cypress because:
+- They can't control native app, they support Web Platform only.
+
+## Negative Consequences
+- The core of this framework will be more complicated than a normal framework that has been built with Selenium.

docs/ADR 002 Why Selenium Appium.md

@@ -0,0 +1,69 @@
+ADR 002: Why Selenium Appium?
+
+Date: 13/09/2024
+
+Status: Approved
+
+## Context
+We need to find way to control Natice App build by Flutter.
+
+## Problem
+Flutter dont give developers full control of UI Element, so it's not easy to locate elements from E2E testing.
+
+## Options
+### 1. Espresso
+
+Pros:
+* Deep Android * integration: Officially supported by Google, ensuring compatibility and stability for Android apps.
+* Fast performance: Runs tests efficiently as it operates directly in the app’s instrumentation.
+* Simple API: Easy to use and read for writing UI tests.
+* Automatic synchronization: Handles waiting for UI elements automatically.
+* Supports various UI tests: Can test complex interactions, including RecyclerView.
+* Strong community support: Well-documented with a large user base.
+
+Cons:
+* Android-only: Does * not support iOS or other platforms.
+* Challenging for complex apps: May struggle with highly dynamic or complex screens.
+* Limited WebView support: Difficult to test apps that heavily rely on WebView.
+* Setup can be tricky: Initial configuration may be complex for beginners.
+
+### 2. Robot 
+
+Pros:
+* Versatile: Can test web, desktop, mobile apps, and APIs with various libraries (e.g., Appium for mobile).
+* Keyword-driven: Easy to write and understand test cases using keyword-based syntax.
+* Cross-platform: Works across multiple platforms and environments.
+* Extensible: Can be extended with custom libraries in Python or Java.
+* Good reporting: Provides detailed reports and logs for test execution.
+
+Cons:
+* Steeper learning curve: The keyword-driven approach may require time to get used to.
+* Not optimized for mobile: Requires additional libraries (like Appium) to test mobile apps, adding complexity.
+* Slower execution: Due to its high-level nature, tests may run slower compared to native frameworks.
+
+### 3. Appium
+
+Pros:
+* Cross-platform: Supports both Android and iOS, allowing testing for multiple platforms with one framework.
+* Language flexibility: Supports various programming languages (Java, Python, JavaScript, C#).
+* Open-source: Free and widely supported by a large community.
+* No app modification: Does not require modifying the app code to run tests.
+* Supports real devices and emulators: Can test on both actual devices and virtual environments.
+
+Cons:
+* Slower execution: Appium tests can be slower, especially on real devices.
+* Complex setup: Initial configuration can be tricky, especially for cross-platform projects.
+* Limited to functional testing: Not ideal for non-functional testing, such as performance or load testing.
+* Less stable on iOS: May experience occasional issues or instability with iOS testing compared to Android.
+
+## Decision
+We choose Appium because:
+- Because it has [Flutter Integration Driver](https://github.com/AppiumTestDistribution/appium-flutter-integration-driver), with this we can do cross platform scenarios from web to moblie.
+
+We did not choose Espresso and Robot because:
+- Some of their cons: not support iOS, community smaller compared with Appium.
+- They also can't work with Selenium.
+
+## Negative Consequences
+- The Flutter Integration Driver is quite new, but its maintainers are very active.
+- It require a build for testing only.

docs/ADR 003 Why Selenium Cucumber.md

@@ -0,0 +1,34 @@
+ADR 003: Why Selenium Cucumber?
+
+Date: 13/09/2024
+
+Status: Approved
+
+## Context
+- Build a framework and use it are 2 separate topics.
+- The question is, how easy is it to write a test case?
+
+## Problem
+- The people who write test cases don't have to understand how the framework has been built; they just need to know how to write and run them.
+- People like Manual Tester and PO can write test cases with less training; there is no need to learn how to code.
+
+## Options
+
+Criteria | Cucumber (BDD) | Method Test Case (TestNG/JUnit)
+-- | -- | --
+Writing Style | Natural language (Gherkin) | Code written directly in methods
+Readability | Easy to read for non-technical stakeholders | Suitable mainly for developers
+Maintenance | Easier to maintain due to clear separation | Can be harder to maintain as test cases grow
+Performance | May be slower due to translation between Gherkin and step definitions | Faster as there is no overhead
+Scalability | Suitable for large projects with multiple stakeholders | Suitable for small projects
+Collaboration | Better for cross-functional teams | Better for technical teams
+
+## Decision
+We choose Cucumber because:
+- QA is not a big team, and we have many products to test, so we have to invoke as many people as possible, not just developers.
+
+We still choose Method Test Case:
+- But this is a second choice when we talk about writing test cases.
+
+## Negative Consequences
+- Build framework with Cucumber require high level of SDET.

docs/ADR 004 Why not choose Testcontainers for Java.md

@@ -0,0 +1,58 @@
+ADR 004: Why not choose Testcontainers for Java?
+
+Date: 16/09/2024
+
+Status: Proposed 
+
+## Context
+We need a testing environment that isolates with another environment, and Testcontainers is the solution the dev team has chosen.
+
+## Problem
+New QA member doesn't think it's a good idea.
+
+## Options
+
+### Testcontainers for Java
+Advantages of Testcontainers:
+* Easy integration with tests: Automatically manages Docker containers within the test code.
+* Isolated environments: Ensures a fresh environment for each test run.
+* Efficient resource usage: Containers start and stop as needed, saving resources.
+* Good CI/CD integration: Works well in automated pipelines for reliable tests.
+
+Disadvantages of Testcontainers:
+* Complex setup for large systems: Managing multiple services can be cumbersome.
+* Slower startup for multiple containers: Initializing many services can take time.
+* Requires programming knowledge: Not as user-friendly for non-developers.
+
+### Local Docker Compose
+Docker Compose Advantages over Testcontainers:
+* Simple configuration: Easy to set up and manage multiple services using a single YAML file.
+* User-friendly: Accessible to both developers and non-developers through a straightforward configuration file.
+* Good for integration tests: Ideal for complex scenarios requiring multiple interdependent services.
+
+Docker Compose Disadvantages compared to Testcontainers:
+* Manual management: Containers need to be started and stopped manually or through additional scripts.
+* Slower startup: May take longer to initialize all services at once.
+* Less integration with test code: Does not provide automatic management of container lifecycle within test code.
+
+### Separate Test Environment
+Advantages of a Separate Test Environment for Selenium:
+* Dedicated resources: Isolates testing environment from development and production, reducing interference.
+* Consistent environment: Ensures tests run in a stable and controlled setup, minimizing external factors.
+* Easier debugging: Dedicated environment can simplify troubleshooting and reproducing issues.
+
+Disadvantages compared to Testcontainers:
+* Resource overhead: Requires maintaining and managing a separate environment, which can be resource-intensive.
+* Manual setup: Initial setup and configuration of the environment can be complex and time-consuming.
+* Less flexibility: Does not offer the dynamic, on-the-fly container management that Testcontainers provides.
+
+## Decision
+- Testcontainers doesn't support rollback test data; we have to write a script for that.
+- Testcontainers has one advantage: it manages Docker containers within the test code, which the QA team will not use because it slows down the test run.
+- Testcontainers make the framework more complicated but don't bring enough benefit to the team.
+- So, we chose Separate Test Environment auto-deployed by using Docker Compose.
+- Separate Test Environment can be use for local and CI/CD test run.
+- About isolates test data for each run; the pre-condition of E2E testing will handle that.
+
+## Negative Consequences
+- None