docs: add TESTS.md with current test status after async forEach fix

- Document 99.6% pass rate (263/264 tests passing)
- Explain that misc-launchql-ext-types.test.ts failure is expected
- Detail how test framework fix revealed previously hidden deparser bug
- Include debugging features and error handling improvements
- Provide testing commands and next steps for deparser bug fix

The failing test demonstrates the async forEach fix is working correctly
by now catching deparser issues that generate invalid SQL.

Co-Authored-By: Dan Lynch <[email protected]>

Author: pyramation

TESTS.md

@@ -0,0 +1,90 @@
+# Test Status Report
+
+**Last Updated:** June 21, 2025  
+**Branch:** devin/1750543497-fix-async-foreach-test-framework  
+**Test Framework:** Jest with custom FixtureTestUtils  
+
+## Current Test Results
+
+After fixing the async forEach bug in the test framework:
+
+```
+Test Suites: 1 failed, 250 passed, 251 total
+Tests:       1 failed, 263 passed, 264 total
+Time:        20.402 seconds
+```
+
+**Pass Rate:** 99.6% (263/264 tests passing)
+
+## Test Framework Fix Impact
+
+The async forEach bug fix in `packages/deparser/test-utils/index.ts` has revealed a previously hidden deparser issue:
+
+### Previously Hidden Failures Now Detected
+
+- **`misc-launchql-ext-types.test.ts`** - Now properly fails due to deparser generating invalid SQL with missing closing quotes in regex patterns
+
+### Root Cause of Test Framework Bug
+
+The test framework was using `tree.stmts.forEach(async (stmt: any) => {` which doesn't properly await async operations. Errors thrown inside the async callback were "fire-and-forget" and never bubbled up to fail tests.
+
+**Fixed by:** Converting to proper `for...of` loop to ensure async operations are awaited and errors are properly caught.
+
+## Failing Tests
+
+### 1. misc-launchql-ext-types.test.ts
+- **Status:** FAILING (Expected - reveals real deparser bug)
+- **Issue:** Deparser drops closing quotes from regex patterns in CREATE DOMAIN CHECK constraints
+- **Example:**
+  ```sql
+  -- Input SQL:
+  CREATE DOMAIN attachment AS jsonb CHECK (value ?& ARRAY['url', 'mime'] AND (value ->> 'url') ~ E'^(https?)://[^\\s/$.?#].[^\\s]*$')
+  
+  -- Deparsed SQL (missing closing quote):
+  CREATE DOMAIN attachment AS jsonb CHECK (value ?& ARRAY['url', 'mime'] AND (value ->> 'url') ~ '^(https?)://[^\s/$.?#].[^\s]*)
+  ```
+- **Error:** `PARSE ERROR: Unexpected token 'u', "unterminat"... is not valid JSON`
+
+## Test Categories
+
+- **Kitchen Sink Tests:** 251 test suites covering comprehensive SQL parsing scenarios
+- **Original Tests:** PostgreSQL upstream test cases
+- **Latest Tests:** Modern PostgreSQL feature tests  
+- **Custom Tests:** LaunchQL-specific extensions and edge cases
+
+## Test Framework Improvements
+
+### Debugging Features Added
+- Detailed SQL comparison logging showing input vs deparsed output
+- Clear indication of exact vs different matches
+- Enhanced error reporting with parse failure details
+
+### Error Handling Fixed
+- Async forEach converted to proper for-of loop
+- Proper error propagation from async operations
+- TypeScript error handling for diff function null cases
+
+## Next Steps
+
+1. **Fix Deparser Bug:** Address the missing quote issue in regex pattern handling
+2. **Verify Fix:** Ensure the deparser properly handles escaped string literals
+3. **Update Tests:** Confirm all tests pass after deparser fix
+4. **Monitor Regressions:** Run full test suite after each change
+
+## Testing Commands
+
+```bash
+# Run all tests
+cd packages/deparser
+yarn test
+
+# Run specific test
+yarn test --testNamePattern="misc-launchql-ext-types"
+
+# Watch mode for development
+yarn test:watch
+```
+
+## Historical Context
+
+This test status reflects the state after fixing a critical async forEach bug that was preventing the test framework from catching deparser failures. The one failing test now properly reveals a real issue that was previously hidden, demonstrating that the test framework fix is working as intended.