Guide for Test Development and Response Crafting

TESTING_GUIDELINES.md

Guide for Test Development and Response Crafting

This document establishes the principles and guidelines for creating automated tests (unit, integration, E2E) and formulating technical responses. The goal is to produce code that is robust, maintainable, and clearly justified, and to provide answers that demonstrate a deep analysis and a complete understanding of the problem.

Part 1: Philosophy and Analysis Process — Think Before Coding

The quality of a test is not measured by its code, but by the thought process that precedes it.

1. Deep Analysis First, Code Later: Before writing a single line of test code, perform a thorough analysis of the function or module to be tested. Your response should begin with this section, describing:

   • The Business Objective: What real-world problem does this function solve? What business questions should it answer? Do not simply describe what the code does; explain why it exists.
   • The Critical Logic: Break down the function into its key logical components. Identify the parts that are most complex or prone to errors (e.g., date calculations, timezone conversions, conditional logic, database queries with multiple JOINs).
   • The Potential Points of Failure: For each logical component, ask yourself: "How could this fail?". Think about off-by-one errors, division by zero, incorrect null handling, race conditions, etc.

2. Explicit Justification for Test Scenarios: Do not just list the test scenarios. For each one, provide a clear justification that directly links it to the previous analysis. Answer the question:

   • "What specific risk does this test mitigate?"
   • Example: "This test validates timezone handling. It is crucial because a failure here would invalidate all reports for users outside of UTC, compromising data integrity on a global scale."

3. Be Rigorous and Exhaustive: Do not settle for superficial coverage. Ensure that the test scenarios cover:

   • The "Happy Path" (the ideal use case).
   • Edge Cases: What happens at the boundaries of a range? (e.g., the first and last second of a day).
   • Error Cases: How does the system react to invalid inputs or missing data?
   • Zero-Result Cases: Does the function gracefully return an empty result, or does it fail?
   • Parameter Combinations: How does the function behave when multiple filters are used simultaneously?

Part 2: Principles for Writing Test Code

1. Total Isolation is Non-Negotiable:

   • Each test (or sub-test t.Run) must be completely independent and must not rely on the state left by a previous test.
   • NEVER use a single data setup function for multiple t.Run blocks if they are not read-only. Each sub-test requiring a specific database state must be responsible for creating and cleaning it up, or the main test must do it for them. Shared state is the primary cause of flaky tests.

2. Absolute Determinism:

   • Do not use dynamic data: Never use uuid.New(), time.Now(), or random data generators for key IDs, timestamps, or values in your test data.
   • Use fixed, hardcoded values: Use uuid.MustParse("...") and time.Parse(...) with constant dates and times. This ensures the test produces the exact same result every time it is run.

3. Structural Clarity (Arrange-Act-Assert):

   • Organize each test clearly:
     1. Arrange: Set up all necessary data and mocks.
     2. Act: Execute the function or endpoint you are testing.
     3. Assert: Compare the obtained result with a static, expected value.
   • Use of Helpers: Helper functions for data setup are acceptable and recommended only if they reduce significant and complex duplication. If a data setup is specific to a single test suite, it is preferable to keep it within that test file to make it self-contained.
   • Comment Style: Comments should precede the line of code they explain, not follow it. They should explain the "why" of an action or assertion, not the "what".

Part 3: Interaction Style and Response Format

1. Response Structure: Organize your responses in a logical and predictable manner:

   1. Acknowledge and validate the feedback received.
   2. Provide a deep analysis of the logic and objective.
   3. Define the test scenarios and their justification.
   4. Present the test code.
   5. If necessary, explain why the new code is superior or how it resolves a previous issue.

2. Controlled Bilingualism:

   • All conversation, explanations, and justifications should be in the user's language (in our case, Spanish).
   • All generated code, including comments, variable names, function names, and error messages, must be strictly in English, following universal software development conventions.

3. Proactivity and Self-Correction:

   • If you identify an error or an insufficiency in one of your previous responses (based on user feedback), acknowledge it explicitly.
   • Explain why the previous approach was incorrect and how the new solution corrects that fundamental flaw. This demonstrates learning and builds trust.