docs: improve module and function documentation

- Add comprehensive module-level docstrings
- Document test categories and markers
- Add detailed function documentation
- Include usage examples and best practices
- Document fixtures and dependencies
- Add error handling documentation

Author: SaahilParmar

conftest.py

@@ -1,3 +1,39 @@
+"""
+conftest.py - Pytest Configuration and Fixtures
+
+This module provides pytest configuration and fixtures for the API testing framework.
+It handles test setup, environment configuration, and common test dependencies.
+
+Configuration:
+    - Defines custom pytest markers
+    - Sets up directory structure for reports
+    - Creates Allure environment properties
+    - Validates configuration files
+
+Fixtures:
+    config (session): Provides access to configuration data
+    base_url (session): Base URL for API requests
+    request_id (function): Unique identifier for each request
+    log_test_start (function): Logs test start with metadata
+
+Usage:
+    The fixtures are automatically available to all test files.
+    Example:
+        def test_get_users(base_url, request_id):
+            response = requests.get(f"{base_url}/users")
+            assert response.status_code == 200
+
+Environment Variables:
+    TEST_ENV: Override the environment from config.yaml (default: 'dev')
+    DEBUG: Enable debug logging (default: False)
+
+Directory Structure:
+    /config/
+        config.yaml: Main configuration file
+    /reports/
+        environment.properties: Allure environment data
+"""
+
 import pytest
 import allure
 import os

tests/test_api_validation.py

@@ -1,22 +1,35 @@
 """
-test_api_validation.py
-
-Test    with allure.step("Send GET request to /users?page=1 with retry resilience"):
-        try:
-            url = f"{base_url}/users?page=1"
-            response = make_resilient_get_request(url, headers=get_headers(), timeout=10)
-            log_request_response(response)  # Enhanced logging
-        except requests.exceptions.RequestException as e:
-            allure.attach(str(e), "Request Error", allure.attachment_type.TEXT)
-            raise
-
-    with allure.step("Verify response status is 200"):cused on API contract validation and da    with allure.step("Send GET request to /users?page=1"):
-        url = f"{base_url}/users?page=1"
-        response = requests.get(url, headers=get_headers())
-        log_request_response(response)  # Enhanced logging
-
-    with allure.step("Verify response status is 200"):tegrity.
-Covers schema validation, header validation, and response format testing.
+test_api_validation.py - API Contract Testing
+
+This module implements contract tests for the ReqRes API, focusing on:
+1. Schema Validation: Ensures API responses match defined JSON schemas
+2. Header Validation: Verifies correct content types and response headers
+3. Response Format: Validates data structure and field types
+4. Error Handling: Tests API error responses and status codes
+
+Test Categories:
+    - Contract Testing (@pytest.mark.contract)
+    - Response Validation (@pytest.mark.response)
+    - Schema Validation (@pytest.mark.schema)
+    - Error Response (@pytest.mark.error)
+
+Each test is documented with:
+    - Purpose and description
+    - Prerequisites and dependencies
+    - Expected results
+    - Allure annotations for reporting
+
+Example Test Structure:
+    @pytest.mark.contract
+    def test_user_schema():
+        1. Send request to API
+        2. Validate response against schema
+        3. Check specific fields
+        4. Verify error cases
+
+Required Fixtures:
+    - base_url: API base URL from config
+    - request_id: Unique test identifier
 """
 
 import pytest

tests/test_error_scenarios.py

@@ -1,10 +1,41 @@
 """
-test_error_scenarios.p        url = f"{base_url}/users/999"
-        response = requests.get(url, headers=get_headers(), timeout=10)
-        log_request_response(response)  # Enhanced logging
-
-    with allure.step("Verify response status is 404"):est module focused on error scenarios and negative testing.
-Covers 404 errors, invalid requests, and edge cases.
+test_error_scenarios.py - API Error Handling Tests
+
+This module implements negative testing and error scenarios for the ReqRes API.
+It verifies that the API handles error conditions gracefully and returns
+appropriate error responses.
+
+Test Categories:
+    - Non-existent Resources (@pytest.mark.not_found)
+    - Invalid Input (@pytest.mark.invalid_input)
+    - Authentication Errors (@pytest.mark.auth)
+    - Rate Limiting (@pytest.mark.rate_limit)
+
+Error Scenarios Tested:
+    1. Resource Not Found (404)
+        - Non-existent users
+        - Deleted resources
+    2. Invalid Requests (400)
+        - Malformed JSON
+        - Missing required fields
+        - Invalid data types
+    3. Authentication (401/403)
+        - Invalid tokens
+        - Missing credentials
+    4. Rate Limiting (429)
+        - Excessive requests
+        - Throttling behavior
+
+Best Practices Implemented:
+    - Detailed error response validation
+    - Error message content verification
+    - HTTP status code checking
+    - Response header validation
+    - Error response schema validation
+
+Required Fixtures:
+    - base_url: API base URL from config
+    - invalid_token: Invalid authentication token
 """
 
 import pytest

tests/test_user_creation.py

@@ -1,8 +1,45 @@
 """
-test_user_creation.py
-
-Test module focused on user creation operations (POST requests).
-Covers data-driven testing, boundary testing, and user creation scenarios.
+test_user_creation.py - User Creation API Tests
+
+This module implements data-driven tests for user creation endpoints in the ReqRes API.
+It focuses on POST operations with various payload combinations and validates the
+creation responses.
+
+Features Tested:
+    1. User Creation
+        - Valid user data
+        - Required fields only
+        - All fields populated
+        - Special characters in names
+    2. Response Validation
+        - Status code (201)
+        - Response schema
+        - Created user data
+    3. Edge Cases
+        - Minimum/maximum field lengths
+        - Unicode characters
+        - Whitespace handling
+
+Test Data:
+    Location: data/post_user_payloads.json
+    Format: List of user creation payloads
+    Example:
+        [
+            {
+                "name": "John Doe",
+                "job": "Developer"
+            },
+            ...
+        ]
+
+Test Categories:
+    - Smoke Tests (@pytest.mark.smoke)
+    - User Creation (@pytest.mark.user_creation)
+    - Data Validation (@pytest.mark.validation)
+
+Required Fixtures:
+    - base_url: API base URL from config
+    - request_id: Unique identifier for each request
 """
 
 import pytest

tests/test_user_retrieval.py

@@ -1,15 +1,43 @@
 """
-test_user_retrieval.py
-        try:
-            url = f"{base_url}/users?page=1"
-            response = requests.get(url, headers=get_headers(), timeout=10)
-            log_request_response(response)  # Enhanced logging
-        except requests.exceptions.RequestException as e:
-            allure.attach(str(e), "Request Error", allure.attachment_type.TEXT)
-            raise
-
-    with allure.step("Verify response status is 200"):dule focused on user retrieval operations (GET requests).
-Covers listing users, retrieving single users, and related functionality.
+test_user_retrieval.py - User Retrieval API Tests
+
+This module implements tests for user retrieval endpoints in the ReqRes API.
+It covers GET operations for both single user and user list endpoints, including
+pagination, filtering, and response validation.
+
+Endpoints Tested:
+    1. List Users (/users)
+        - Pagination
+        - Per page limits
+        - Total count validation
+    2. Single User (/users/{id})
+        - Valid user IDs
+        - Response format
+        - User data structure
+    3. User Filtering
+        - Query parameters
+        - Sort options
+        - Field selection
+
+Response Validation:
+    - Status codes (200, 404)
+    - JSON schema compliance
+    - Data structure
+    - Field types and formats
+    - Pagination metadata
+
+Test Categories:
+    - Smoke Tests (@pytest.mark.smoke)
+    - User Retrieval (@pytest.mark.user_retrieval)
+    - Pagination (@pytest.mark.pagination)
+
+Required Fixtures:
+    - base_url: API base URL from config
+    - request_id: Unique identifier for each request
+
+Schema Validation:
+    Uses schemas/user_list_schema.json and schemas/single_user_schema.json
+    to validate response formats
 """
 
 import pytest

utils/api_utils.py

@@ -1,12 +1,39 @@
 """
-api_utils.py
-
-Utility functions for API test automation:
-- Loads configuration and schema files.
-- Provides default HTTP headers.
-- Implements request retry logic.
-- Attaches request/response details to Allure reports.
-- Validates API responses against JSON schemas.
+api_utils.py - API Testing Utility Functions
+
+This module provides core functionality for API testing, including:
+- Configuration management (loading and parsing config files)
+- Schema validation (JSON schema loading and response validation)
+- HTTP request handling (headers, retry logic, response processing)
+- Test reporting (Allure integration for requests and responses)
+- Error handling (custom exceptions and retry mechanisms)
+
+The module is designed to work with the ReqRes API (https://reqres.in/) but can be
+adapted for any RESTful API testing needs.
+
+Classes:
+    None
+
+Functions:
+    load_config() -> dict: Load and parse the config.yaml file
+    load_schema(schema_filename: str) -> dict: Load a JSON schema file
+    get_headers() -> dict: Get default HTTP headers from config
+    retry_request(func) -> callable: Decorator for request retry logic
+    validate_response(response: Response, schema: dict) -> None: Validate response against schema
+    attach_request_details(response: Response) -> None: Add request details to Allure report
+
+Dependencies:
+    - pyyaml: For parsing config.yaml
+    - requests: For HTTP requests
+    - jsonschema: For JSON schema validation
+    - allure-pytest: For test reporting
+
+Example Usage:
+    >>> config = load_config()
+    >>> headers = get_headers()
+    >>> response = requests.get(f"{config['base_url']}/users", headers=headers)
+    >>> schema = load_schema("user_list_schema.json")
+    >>> validate_response(response, schema)
 """
 
 import yaml