fix(tests): Stabilize tests and document chokidar-inspired Node watcher architecture

test/test.basic.ts

@@ -35,6 +35,30 @@ async function waitForEvent<T>(
   });
 }
 
+// Helper to wait for a specific file's event (filters by filename)
+async function waitForFileEvent<T extends [string, ...any[]]>(
+  observable: smartrx.rxjs.Observable<T>,
+  expectedFile: string,
+  timeoutMs: number = 5000
+): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      subscription.unsubscribe();
+      reject(new Error(`Timeout waiting for event on ${expectedFile} after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    const subscription = observable.subscribe((value) => {
+      const [filePath] = value;
+      if (filePath.includes(expectedFile)) {
+        clearTimeout(timeout);
+        subscription.unsubscribe();
+        resolve(value);
+      }
+      // Otherwise keep waiting for the right file
+    });
+  });
+}
+
 let testSmartwatch: smartwatch.Smartwatch;
 
 // ===========================================
@@ -63,8 +87,9 @@ tap.test('should detect ADD event for new files', async () => {
   const [filePath] = await eventPromise;
   expect(filePath).toInclude('add-test.txt');
 
-  // Cleanup
+  // Cleanup - wait for atomic delay to complete (100ms debounce + 100ms atomic)
   await fs.promises.unlink(testFile);
+  await delay(250);
 });
 
 tap.test('should detect CHANGE event for modified files', async () => {
@@ -84,8 +109,9 @@ tap.test('should detect CHANGE event for modified files', async () => {
   const [filePath] = await eventPromise;
   expect(filePath).toInclude('change-test.txt');
 
-  // Cleanup
+  // Cleanup - wait for atomic delay to complete
   await fs.promises.unlink(testFile);
+  await delay(250);
 });
 
 tap.test('should detect UNLINK event for deleted files', async () => {
@@ -97,7 +123,9 @@ tap.test('should detect UNLINK event for deleted files', async () => {
   await delay(200);
 
   const unlinkObservable = await testSmartwatch.getObservableFor('unlink');
-  const eventPromise = waitForEvent(unlinkObservable);
+
+  // Use file-specific wait to handle any pending unlinks from other tests
+  const eventPromise = waitForFileEvent(unlinkObservable, 'unlink-test.txt');
 
   // Delete the file
   await fs.promises.unlink(testFile);