Testing Guidelines and TDD Workflow

Relevant source files

• Qoder/prompt.txt
• README.md

Purpose and Scope

This document describes Qoder's testing guidelines and Test-Driven Development (TDD) workflow for writing, executing, and iterating on unit tests. Qoder follows a strict single-file validation approach that ensures code quality through incremental test generation and immediate execution. For general code validation mechanisms beyond testing, see Code Change Validation Pipeline. For parallel execution constraints that affect test runs, see Parallel Tool Execution Strategy.

Sources: Qoder/prompt.txt82-97

---

Core Testing Philosophy

Qoder operates under the acknowledgment that initial implementations often contain errors, but through diligent test iteration, achieves superior outcomes. The system is designed to be proficient at writing unit tests and, more importantly, making them work through systematic refinement.

Fundamental Testing Principles

Principle	Implementation	Rationale
Test Suggestion	Suggest tests after writing code	Ensures code correctness verification
Immediate Execution	Execute tests immediately after writing	Provides rapid feedback loop
Iterative Refinement	Continue fixing until tests pass	Achieves working implementations
Single-File Focus	Generate ONE test file at a time	Prevents complexity cascade
Mandatory Validation	Use get_problems before execution	Catches compilation issues early

The system proactively suggests test creation after implementing code changes, establishing a quality gate before considering work complete.

Sources: Qoder/prompt.txt82-85 Qoder/prompt.txt206-210 Qoder/prompt.txt232

---

Single-File Validation Workflow

Qoder enforces a strict single-file validation protocol when generating multiple test files. This sequential approach prevents cascading compilation errors and maintains code stability throughout the testing process.

Testing Workflow - Complete Cycle

Sources: Qoder/prompt.txt88-97 Qoder/prompt.txt206-210

Single-File Generation Rules

The following strict rules govern multi-file test generation:

1. Generate ONE test file - Never generate multiple test files simultaneously
2. Validate with get_problems - Check for compilation/lint issues immediately after writing
3. Fix all issues - Resolve any compilation problems before proceeding
4. Sequential progression - Only advance to next test file after current file compiles successfully
5. No token limit concerns - Qoder will be called multiple times; focus on current file quality only

This protocol prevents the common failure mode where multiple broken test files create overwhelming debugging complexity.

Sources: Qoder/prompt.txt88-93

---

Test Execution and Iteration Cycle

After successfully compiling a test file, Qoder enters the execution-iteration cycle that continues until all tests pass.

Execution Requirements

Requirement	Tool/Method	Mandatory
Pre-execution knowledge	Understand test execution method	Yes
Immediate execution	Use run_in_terminal tool	Yes
Result reporting	Report test results to user	Yes
Failure analysis	Diagnose why tests failed	Yes
Iterative fixing	Fix code and re-run tests	Yes

Before executing any tests, Qoder must determine the correct test execution method for the project (e.g., npm test, pytest, cargo test, etc.). This prevents failed test runs due to incorrect invocation.

Sources: Qoder/prompt.txt95-97 Qoder/prompt.txt206-210

Iteration Until Success

The system iterates through the execution-analysis-fix cycle until achieving passing tests, resulting in robust, validated implementations. Qoder's self-acknowledged tendency to "mess up initial implementations" is compensated by diligent iteration.

Sources: Qoder/prompt.txt84-85 Qoder/prompt.txt208

---

Multi-File Test Generation Protocol

When a testing task requires multiple test files, Qoder follows a strict sequential generation protocol that ensures each file is fully validated before proceeding to the next.

Sequential Test File Generation

Protocol Requirements

The multi-file generation protocol enforces these requirements:

• No parallel test file generation - Files must be created sequentially
• Full validation per file - Each file must pass get_problems before execution
• Execution verification - Each test file must be executed and pass before proceeding
• Multiple invocation awareness - Qoder acknowledges it will be called multiple times; no rush needed
• Quality over speed - Focus on correctness of current file, not completion of all files

This approach prevents the accumulation of compilation errors across multiple files and ensures each test suite is independently verified.

Sources: Qoder/prompt.txt88-93 Qoder/prompt.txt209-210

---

Integration with Code Validation Pipeline

Test generation is tightly integrated with Qoder's mandatory code validation pipeline, which uses the get_problems tool to detect compilation and lint errors.

Test File Validation Flow

The get_problems tool serves as a critical quality gate before test execution, catching issues that would cause test runs to fail due to compilation errors rather than logic errors. This separation of concerns allows Qoder to systematically address different error types.

Sources: Qoder/prompt.txt89-92 Qoder/prompt.txt146-150 Qoder/prompt.txt318

---

Best Practices and Operational Guidelines

When to Write Tests

Qoder follows a test-suggestion workflow where tests are recommended after implementing code changes:

Scenario	Test Recommendation	Timing
New feature implementation	Always suggest tests	After code completion
Bug fix	Suggest regression test	After fix implementation
Refactoring	Suggest existing test execution	After refactor
Code edit completion	Suggest writing/updating tests	End of edit session

The system explicitly prompts: "If you have made code edits, suggest writing or updating tests and executing those tests to make sure the changes are correct."

Sources: Qoder/prompt.txt206 Qoder/prompt.txt232

Test Execution Knowledge

Before running any tests, Qoder must determine the appropriate test execution method:

• Framework detection - Identify testing framework (Jest, pytest, JUnit, etc.)
• Command knowledge - Know the correct test invocation command
• Configuration awareness - Understand any special test configuration requirements
• Environment setup - Ensure necessary environment variables or dependencies are available

This pre-execution knowledge gathering prevents wasted cycles on failed test runs due to incorrect invocation methods.

Sources: Qoder/prompt.txt95-96

Terminal Tool Usage

Tests are executed using the run_in_terminal tool, which must adhere to Qoder's parallel execution constraints:

• Sequential execution only - run_in_terminal must NEVER be called in parallel
• Background process support - Available for long-running test suites or watch modes
• Output retrieval - Use get_terminal_output to retrieve background process results

This ensures proper test execution order and prevents race conditions in test runs.

Sources: Qoder/prompt.txt69 Qoder/prompt.txt75 Qoder/prompt.txt313-314

Iterative Improvement Philosophy

Qoder's testing approach embraces an iterative improvement model:

1. Acknowledge imperfection - Initial implementations often have issues
2. Rapid feedback - Immediate test execution provides quick feedback
3. Systematic fixing - Analyze failures and fix root causes
4. Diligent iteration - Continue until tests pass
5. Better outcomes - Result is typically much better than initial attempt

This philosophy contrasts with attempting perfect implementations on the first try, instead relying on the test suite to guide refinement toward correctness.

Sources: Qoder/prompt.txt84-85

---

Tool Integration Reference

Testing-Related Tools

Tool	Purpose	Usage in Testing
get_problems	Detect compilation/lint errors	Validate test file before execution
run_in_terminal	Execute shell commands	Run test suite commands
get_terminal_output	Retrieve background process output	Get test results from background test runners
create_file	Create new files (max 600 lines)	Generate new test files
search_replace	Make precise code edits	Fix test failures or implementation bugs

Tool Sequence for Single Test

This tool sequence forms the core testing workflow, with get_problems serving as the validation gate between test generation and execution.

Sources: Qoder/prompt.txt306-323 Qoder/prompt.txt88-97

---

Summary

Qoder's testing guidelines establish a disciplined TDD workflow centered on single-file validation, immediate execution, and iterative refinement. The system's self-awareness of initial implementation imperfection, combined with diligent iteration on test failures, produces robust, well-tested code. The strict sequential test file generation protocol prevents complexity cascade, while mandatory get_problems validation ensures compilation correctness before test execution. This systematic approach transforms testing from an afterthought into a core quality assurance mechanism integrated throughout the development workflow.

Sources: Qoder/prompt.txt82-97 Qoder/prompt.txt206-210 Qoder/prompt.txt232