doc: list macOS as supporting filename argument

also added regression tests

PR-URL: #13111
Fixes: #13108
Reviewed-By: Refael Ackermann <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Alexey Orlenko <[email protected]>

Author: Chris Young

doc/api/fs.md

@@ -2297,10 +2297,10 @@ this improves the usability of file watching. This is expected behavior.
 
 <!--type=misc-->
 
-Providing `filename` argument in the callback is only supported on Linux and
-Windows.  Even on supported platforms, `filename` is not always guaranteed to
-be provided. Therefore, don't assume that `filename` argument is always
-provided in the callback, and have some fallback logic if it is null.
+Providing `filename` argument in the callback is only supported on Linux,
+macOS, Windows, and AIX.  Even on supported platforms, `filename` is not always
+guaranteed to be provided. Therefore, don't assume that `filename` argument is
+always provided in the callback, and have some fallback logic if it is null.
 
 ```js
 fs.watch('somedir', (eventType, filename) => {

test/parallel/test-fs-watchfile.js

@@ -63,3 +63,21 @@ fs.watchFile(enoentFile, {interval: 0}, common.mustCall(function(curr, prev) {
     fs.unwatchFile(enoentFile);
   }
 }, 2));
+
+// Watch events should callback with a filename on supported systems
+if (common.isLinux || common.isOSX || common.isWindows || common.isAix) {
+  const dir = common.tmpDir + '/watch';
+
+  fs.mkdir(dir, common.mustCall(function(err) {
+    if (err) assert.fail(err);
+
+    fs.watch(dir, common.mustCall(function(eventType, filename) {
+      this._handle.close();
+      assert.strictEqual(filename, 'foo.txt');
+    }));
+
+    fs.writeFile(`${dir}/foo.txt`, 'foo', common.mustCall(function(err) {
+      if (err) assert.fail(err);
+    }));
+  }));
+}