Asynchronous File Watcher Tests

Build a simple test suite for an asynchronous file watcher module that notifies callbacks when file changes are detected.

Background

You are working with a file watcher utility that monitors files and triggers callbacks when changes occur. The watcher uses callback-based APIs rather than promises. You need to write tests for this callback-based asynchronous behavior.

Requirements

Create a test suite that validates the file watcher's callback-based behavior:

1. File Change Detection: When a file change is detected, the watcher should call the registered callback with the changed file path
2. Multiple Callbacks: The watcher should support registering multiple callbacks and call all of them when changes occur
3. Error Handling: If an error occurs during file watching, the watcher should call the callback with an error parameter
4. Timeout Behavior: Callbacks should be invoked within a reasonable time frame (configurable, default 1000ms)

The file watcher module has the following interface:

class FileWatcher {
  // Starts watching a file and calls callback when changes occur
  // callback signature: (error, filePath) => void
  watch(filePath, callback) { }

  // Simulates a file change (for testing purposes)
  simulateChange(filePath) { }

  // Simulates an error (for testing purposes)
  simulateError(filePath, error) { }
}

Implementation Tasks

1. Create a file file-watcher.js that implements the FileWatcher class with the interface described above. The implementation should invoke callbacks asynchronously (e.g., using setTimeout) to simulate real async file system operations.
2. Create test file(s) that verify the callback-based asynchronous behavior. Tests must properly handle async callbacks and signal when the asynchronous operation is complete.

Test Cases

Your test suite must include the following test cases:

• Given a file watcher watching "test.txt", when a change is simulated, then the callback should be invoked with (null, "test.txt") @test
• Given a file watcher with two registered callbacks on "test.txt", when a change is simulated, then both callbacks should be invoked @test
• Given a file watcher watching "test.txt", when an error is simulated with "Permission denied", then the callback should be invoked with the error @test
• Given a file watcher watching "test.txt" with a 500ms timeout, when a change is simulated, then the callback should be invoked within 500ms @test

Implementation

@generates

API

/**
 * A simple file watcher that monitors files and triggers callbacks on changes.
 */
class FileWatcher {
  /**
   * Start watching a file and register a callback to be invoked on changes.
   * @param {string} filePath - The path of the file to watch
   * @param {Function} callback - Callback function with signature (error, filePath) => void
   */
  watch(filePath, callback) { }

  /**
   * Simulate a file change for testing purposes.
   * Invokes all registered callbacks for the file with (null, filePath).
   * @param {string} filePath - The path of the file that changed
   */
  simulateChange(filePath) { }

  /**
   * Simulate an error for testing purposes.
   * Invokes all registered callbacks for the file with (error, null).
   * @param {string} filePath - The path of the file
   * @param {Error} error - The error to pass to callbacks
   */
  simulateError(filePath, error) { }
}

module.exports = FileWatcher;

Dependencies { .dependencies }

jest { .dependency }

Provides the testing framework for writing callback-based asynchronous tests.