Test Case Specifications

Clear and comprehensive test case specifications are fundamental to ensuring the quality, reliability, and security of the Gemforce platform's smart contracts, cloud functions, and API services. This document outlines the guidelines for writing effective test cases, ensuring thorough coverage and repeatability.

1. Principles of Good Test Case Design

  • Atomicity: Each test case should focus on testing a single, specific functionality or unit of code.
  • Independence: Test cases should be independent of each other. The order of execution should not affect the outcome of any individual test.
  • Repeatability: A test case should produce the same result every time it is executed, given the same inputs and environment.
  • Maintainability: Test cases should be easy to understand, modify, and extend as the system evolves.
  • Traceability: Each test case should be traceable back to a specific requirement or user story.
  • Completeness: Test cases should cover all defined requirements, including positive, negative, edge, and boundary conditions.

2. Structure of a Test Case

Each test case should follow a consistent structure to ensure clarity and ease of understanding.

  • Test Case ID: A unique identifier (e.g., SC-FC-001, API-AUTH-005, CF-TD-010).
  • Test Case Title: A concise, descriptive title summarizing the objective (e.g., "Verify successful creation of carbon credit NFT").
  • Module/Component: The specific module or component being tested (e.g., CarbonCreditFacet, AuthFunctions, TradeDealService).
  • Requirement/User Story (Optional but Recommended): Reference to the requirement or user story being covered by the test.
  • Preconditions: Any conditions that must be met before executing the test (e.g., "User is authenticated," "Smart contract is deployed," "Database contains X data").
  • Test Data: Specific input values, parameters, and expected states required for the test.
  • Steps to Execute: A clear, ordered list of actions to perform.
  • Expected Result: The verifiable outcome of executing the steps. This should be precise and measurable.
  • Postconditions (Optional): Any state changes or clean-up actions after the test completes.
  • Priority: (e.g., High, Medium, Low)
  • Status: (e.g., Draft, Ready, In Progress, Failed, Passed)

3. Types of Test Cases

3.1. Smart Contract Test Cases

Focus on the Solidity code and its interaction with the EVM.

  • Unit Tests: Verify individual functions or contract components in isolation.
    • Example: Test mint function in GemforceMinterFacet for valid inputs.
  • Integration Tests: Verify the interaction between multiple smart contracts or facets.
    • Example: Test the flow of creating a Trade Deal, adding collateral, and liquidating it, involving TradeDealAdminFacet and TradeDealOperationsFacet.
  • Security Tests: Specifically target known vulnerabilities (e.g., reentrancy, integer overflows, access control bypass).
    • Example: Test for reentrancy attack on critical withdrawal functions.
  • Gas Optimization Tests: Measure gas consumption for critical functions and identify areas for optimization.

3.2. Cloud Function / API Test Cases

Focus on backend logic, database interactions, and external service integrations.

  • Unit Tests: Test individual cloud functions or API endpoints in isolation.
    • Example: Test createIdentity cloud function with valid/invalid inputs.
  • Integration Tests: Validate the end-to-end flow involving multiple cloud functions, external APIs (e.g., DFNS, SendGrid), or database operations.
    • Example: Test user registration flow from API call to database persistence and email verification.
  • Performance Tests: Assess response times, throughput, and scalability under load.
  • Security Tests: Focus on API authentication, authorization, input validation, and preventing common web vulnerabilities (e.g., OWASP Top 10).
    • Example: Attempt unauthenticated access to a protected API endpoint.
  • Error Handling Tests: Verify that backend services return appropriate error messages and status codes for various failure scenarios.

3.3. UI/UX Test Cases (if applicable)

Focus on the user interface and user experience, primarily for front-end applications.

  • Functional Tests: Verify that UI elements behave as expected according to specifications.
  • Usability Tests: Assess the ease of use and user-friendliness of the application.
  • Compatibility Tests: Ensure the application functions correctly across different browsers, devices, and operating systems.

4. Test Data Management

  • Realistic Data: Use data that closely resembles production data, but sanitize or anonymize sensitive information.
  • Edge Cases and Boundary Values: Include data that tests the limits of input fields or system logic.
  • Negative Data: Test with invalid, malformed, or out-of-range data to ensure proper error handling.
  • Version Control: Manage test data and configurations under version control.
  • Automated Generation: For large-scale testing, consider tools for automated test data generation.

5. Examples

Example: Smart Contract Test Case (ERC-721A Minting)

Test Case ID: SC-MINT-001 Test Case Title: Verify successful minting of single NFT by valid user Module/Component: GemforceMinterFacet.sol Requirement: The smart contract shall allow a user to mint an NFT from an active batch if they provide the correct payment and batch details. Preconditions: * GemforceMinterFacet is deployed and added to the Diamond. * Minting batch ID 1 is configured with pricePerToken = 1 ETH, maxSupply = 100, maxMintPerWallet = 5, and is currently active (mintStart < block.timestamp < mintEnd). * User account Alice has at least 1 ETH balance. Test Data: * _batchId: 1 * _count: 1 * _merkleProof: [] (empty, as no whitelist) * msg.value: 1 ETH * msg.sender: Alice Steps to Execute: 1. Call mint(batchId, count, merkleProof) from Alice's account with the specified msg.value. 2. Check the return value (if any). 3. Check the contract's state. Expected Result: 1. Transaction succeeds without error. 2. Minted event is emitted with minter = Alice, batchId = 1, count = 1. 3. GemforceMinterFacet balance decreases by 1 ETH. 4. Total supply of NFTs for batch 1 increases by 1. 5. Alice's NFT balance increases by 1. 6. Alice's msg.value decreases by 1 ETH.

Example: Cloud Function Test Case (User Authentication)

Test Case ID: CF-AUTH-003 Test Case Title: Verify failed login with invalid password Module/Component: AuthFunctions.js (Login endpoint) Requirement: The login endpoint shall return an error if an invalid password is provided for a registered user. Preconditions: * Parse Server is running. * User testuser@example.com is registered with password correctpassword123. Test Data: * username: testuser@example.com * password: wrongpassword Steps to Execute: 1. Send a POST request to /parse/functions/login with the provided username and password. 2. Inspect the HTTP response status code and body. Expected Result: 1. HTTP Status Code is 400 (Bad Request) or 401 (Unauthorized), depending on API design. 2. Response body contains an error message indicating "Invalid username/password" or similar. 3. No new session token is created for testuser@example.com.