docs: Add Known Test Workarounds section to testing documentation

Author: ipv1337

docs/TESTING.md

@@ -170,4 +170,17 @@ Recent work with the Google Generative AI (Gemini) API highlighted several key l
 
 3. **Regular Updates**: Update tests when APIs change, focusing on the behavior rather than the exact implementation.
 
-4. **Error Handling**: Include proper error handling in tests to make them more robust against changes. 
+4. **Error Handling**: Include proper error handling in tests to make them more robust against changes. 
+
+### Known Test Workarounds
+
+1. **Gemini Agent Loop Issues**: The Gemini agent loop has limitations in handling sequences of tool calls.
+   - Several tests in `tests/models/test_gemini.py` have modified assertions to accommodate these limitations:
+     - `test_generate_simple_tool_call` has commented-out assertions for the second tool execution (`mock_task_complete_tool.execute`) and final result check.
+     - History count assertions are adjusted to reflect actual behavior rather than ideal behavior.
+   - When writing new tests that involve sequential tool calls, be aware of these limitations and adjust assertions accordingly.
+   - If you're improving the agent loop functionality, consult `TODO_gemini_loop.md` for details on remaining issues.
+
+2. **Mock API Response Structure**: Some tests may have extra or adjusted mock structures to handle the model's specific response processing.
+   - Look for comments like `# Mock response adapted for agent loop` to identify these cases.
+   - When updating these tests, ensure you maintain the adjusted structure until the underlying issues are resolved.