From 8b48a1bf741eb8aa4925dce5ac3f5ff0d9f18f26 Mon Sep 17 00:00:00 2001 From: Arpita kesharwani <107834813+KesharwaniArpita@users.noreply.github.com> Date: Sun, 27 Oct 2024 17:10:21 +0530 Subject: [PATCH 1/3] Update CONTRIBUTING.md Added Testing conventions --- CONTRIBUTING.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ac114781..eef6dba2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -143,6 +143,8 @@ Scribe-Android uses pre-commit hooks to maintain a clean and consistent codebase ## Testing [`⇧`](#contents) +Writing unit tests is essential to guarantee the dependability, sustainability, and excellence of the Scribe Android codebase. Unit tests confirm that individual components of the application work as intended, detecting errors at an early stage, making the debugging process easier, and boosting assurance for upcoming modifications. An unchanging testing method helps new team members grasp project norms and anticipated actions. + In addition to the [pre-commit](https://pre-commit.com/) hooks that are set up during the [development environment section](#dev-env), Scribe-Android includes a testing suite that should be ran before all pull requests and subsequent commits. Please run the following in the project root: ```bash @@ -159,6 +161,66 @@ ktlint --format +### Unit Testing Conventions for Scribe Android + +To maintain consistency and clarity in the Scribe Android codebase, we recommend you to follow these conventions when writing unit tests. These guidelines cover the organization, naming conventions, scope, and structure for unit tests. + +#### 1. Project Structure for Unit Tests + +- **Location**: Place all unit tests in the `src/test/java` directory, mirroring the structure of the `src/main/java` directory. For new classes or features, ensure their corresponding test classes follow the same package structure. +- **Class Files**: Each class in `src/main/java` should have a dedicated test file in `src/test/java`, named by appending `Test` to the class name (e.g., `UserManager` → `UserManagerTest`). +- **New Classes for Testing**: When a new utility or helper class is needed specifically for testing, place it under `src/test/java/utils` or `src/test/java/helpers`. + +#### 2. Naming Conventions for Tests + +- **Test Methods**: Use descriptive names indicating expected behavior. Follow the format: + + ```java + @Test + public void methodName_StateUnderTest_ExpectedBehavior() { + // Test code here + } + ``` + + Example: `saveUser_WithValidData_SavesUserCorrectly()`. + +- **Descriptive Names**: Avoid generic names like `testMethod1`. Focus on what’s being tested and the expected outcome, such as `calculateTotal_WithDiscount_AppliesDiscountCorrectly`. + +#### 3. Scope and Focus of Tests + +- **Single Responsibility**: Each test should cover only one behavior or scenario. For multiple behaviors, split them into separate test methods. +- **Setup and Teardown**: Use `@Before` for initializing objects and `@After` for cleanup, ensuring tests run in isolation. + + ```java + @Before + public void setUp() { + // Initialize objects + } + + @After + public void tearDown() { + // Cleanup objects + } + ``` + +- **Mocking**: Use mocks (e.g., Mockito) to isolate the unit under test, especially with dependencies like databases, network requests, or services. + +#### 4. Writing Effective Tests + +- **AAA Pattern (Arrange, Act, Assert)**: Structure each test with three distinct parts: + - **Arrange**: Set up the conditions. + - **Act**: Execute the method under test. + - **Assert**: Verify the result. + +- **Coverage of Edge Cases**: Write tests for both typical cases and edge cases, like `null` values or invalid data. + +#### 5. Test Documentation + +- **Comments**: Add comments when test logic is complex or non-intuitive. +- **Assertions**: Use descriptive assertion methods (`assertTrue`, `assertEquals`, etc.) for clarity and include failure messages for custom assertions if necessary. + +Following these conventions ensures consistent, readable, and reliable unit tests, enhancing the quality of the Scribe Android codebase. + # Issues and projects [`⇧`](#contents) The [issue tracker for Scribe-Android](https://github.com/scribe-org/Scribe-Android/issues) is the preferred channel for [bug reports](#bug-reports), [features requests](#feature-requests) and [submitting pull requests](#pull-requests). Scribe also organizes related issues into [projects](https://github.com/scribe-org/Scribe-Android/projects). From 773bde21fe57a5976f1c75a2582ac080c39a2da0 Mon Sep 17 00:00:00 2001 From: Andrew Tavis McAllister Date: Wed, 30 Oct 2024 23:17:35 +0100 Subject: [PATCH 2/3] Remove repeat entries and format testing docs --- CONTRIBUTING.md | 67 +++++++++++++++++++++++-------------------------- 1 file changed, 32 insertions(+), 35 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index eef6dba2..956f94fa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -167,59 +167,56 @@ To maintain consistency and clarity in the Scribe Android codebase, we recommend #### 1. Project Structure for Unit Tests -- **Location**: Place all unit tests in the `src/test/java` directory, mirroring the structure of the `src/main/java` directory. For new classes or features, ensure their corresponding test classes follow the same package structure. -- **Class Files**: Each class in `src/main/java` should have a dedicated test file in `src/test/java`, named by appending `Test` to the class name (e.g., `UserManager` → `UserManagerTest`). -- **New Classes for Testing**: When a new utility or helper class is needed specifically for testing, place it under `src/test/java/utils` or `src/test/java/helpers`. +- **Location**: Place all unit tests in the `src/test/java` directory to mirror the structure of the `src/main/java` directory. For new classes or features, ensure their corresponding test classes follow the same package structure. +- **Class Files**: Each class in `src/main/java` should have a dedicated test file in `src/test/java`, named by appending `Test` to the class name (e.g., `UserManager` → `UserManagerTest`). +- **New Classes for Testing**: When a new utility or helper class is needed specifically for testing, place it under `src/test/java/utils` or `src/test/java/helpers`. #### 2. Naming Conventions for Tests -- **Test Methods**: Use descriptive names indicating expected behavior. Follow the format: +- **Test Methods**: Use descriptive names indicating expected behavior. Follow the format: - ```java - @Test - public void methodName_StateUnderTest_ExpectedBehavior() { - // Test code here - } - ``` - - Example: `saveUser_WithValidData_SavesUserCorrectly()`. + ```kotlin + @Test + public void methodName_StateUnderTest_ExpectedBehavior() { + // Test code here + } + ``` -- **Descriptive Names**: Avoid generic names like `testMethod1`. Focus on what’s being tested and the expected outcome, such as `calculateTotal_WithDiscount_AppliesDiscountCorrectly`. + Example: `saveUser_WithValidData_SavesUserCorrectly()`. #### 3. Scope and Focus of Tests -- **Single Responsibility**: Each test should cover only one behavior or scenario. For multiple behaviors, split them into separate test methods. -- **Setup and Teardown**: Use `@Before` for initializing objects and `@After` for cleanup, ensuring tests run in isolation. +- **Single Responsibility**: Each test should cover only one behavior or scenario. For multiple behaviors, split them into separate test methods. +- **Setup and Teardown**: Use `@Before` for initializing objects and `@After` for cleanup, ensuring tests run in isolation. - ```java - @Before - public void setUp() { - // Initialize objects - } + ```kotlin + @Before + public void setUp() { + // Initialize objects + } - @After - public void tearDown() { - // Cleanup objects - } - ``` + @After + public void tearDown() { + // Cleanup objects + } + ``` -- **Mocking**: Use mocks (e.g., Mockito) to isolate the unit under test, especially with dependencies like databases, network requests, or services. +- **Mocking**: Use mocks (e.g., MockK) to isolate the unit test, especially with dependencies like databases, network requests or services. #### 4. Writing Effective Tests -- **AAA Pattern (Arrange, Act, Assert)**: Structure each test with three distinct parts: - - **Arrange**: Set up the conditions. - - **Act**: Execute the method under test. - - **Assert**: Verify the result. +- **AAA Pattern (Arrange, Act, Assert)**: Structure each test with three distinct parts: -- **Coverage of Edge Cases**: Write tests for both typical cases and edge cases, like `null` values or invalid data. + - **Arrange**: Set up the conditions. + - **Act**: Execute the method under test. + - **Assert**: Verify the result. -#### 5. Test Documentation +- **Coverage of Edge Cases**: Write tests for both typical cases and edge cases, like `null` values or invalid data. -- **Comments**: Add comments when test logic is complex or non-intuitive. -- **Assertions**: Use descriptive assertion methods (`assertTrue`, `assertEquals`, etc.) for clarity and include failure messages for custom assertions if necessary. +#### 5. Test Documentation -Following these conventions ensures consistent, readable, and reliable unit tests, enhancing the quality of the Scribe Android codebase. +- **Comments**: Add comments when test logic is complex or non-intuitive. +- **Assertions**: Use descriptive assertion methods (`assertTrue`, `assertEquals`, etc.) for clarity and include failure messages for custom assertions if necessary. # Issues and projects [`⇧`](#contents) From c68760db187f2f1dd37bbc920f09e6d7bb4a62ee Mon Sep 17 00:00:00 2001 From: Andrew Tavis McAllister Date: Wed, 30 Oct 2024 23:20:26 +0100 Subject: [PATCH 3/3] Fix to project name in testing within contributing docs --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 956f94fa..60ec7c59 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -143,7 +143,7 @@ Scribe-Android uses pre-commit hooks to maintain a clean and consistent codebase ## Testing [`⇧`](#contents) -Writing unit tests is essential to guarantee the dependability, sustainability, and excellence of the Scribe Android codebase. Unit tests confirm that individual components of the application work as intended, detecting errors at an early stage, making the debugging process easier, and boosting assurance for upcoming modifications. An unchanging testing method helps new team members grasp project norms and anticipated actions. +Writing unit tests is essential to guarantee the dependability and sustainability of the Scribe-Android codebase. Unit tests confirm that individual components of the application work as intended, detecting errors at an early stage, making the debugging process easier and boosting assurance for upcoming modifications. An unchanging testing method helps new team members grasp project norms and anticipated actions. In addition to the [pre-commit](https://pre-commit.com/) hooks that are set up during the [development environment section](#dev-env), Scribe-Android includes a testing suite that should be ran before all pull requests and subsequent commits. Please run the following in the project root: @@ -161,9 +161,9 @@ ktlint --format -### Unit Testing Conventions for Scribe Android +### Unit Testing Conventions for Scribe-Android -To maintain consistency and clarity in the Scribe Android codebase, we recommend you to follow these conventions when writing unit tests. These guidelines cover the organization, naming conventions, scope, and structure for unit tests. +To maintain consistency and clarity in the Scribe-Android codebase, we recommend you to follow these conventions when writing unit tests. These guidelines cover the organization, naming conventions, scope, and structure for unit tests. #### 1. Project Structure for Unit Tests