doc,test: documents behaviour of non-existent file

As per the discussion in
https://github.com/nodejs/io.js/pull/2093#discussion_r34343965, this
patch documents the behavior of calling fs.watchFile() with a path that
does not yet exist.

This patch also includes a test which checks if a file not present, the
callback is invoked at least once and if the file is created after
the callback is invoked, it will be invoked again with new stat
objects.

PR-URL: https://github.com/nodejs/io.js/pull/2169
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Brendan Ashworth <brendan.ashworth@me.com>

1 files changed, 57 insertions, 5 deletions

diff --git a/test/parallel/test-fs-watchfile.js b/test/parallel/test-fs-watchfile.js
index eacb2f9d82..35712741f7 100644
--- a/test/parallel/test-fs-watchfile.js
+++ b/test/parallel/test-fs-watchfile.js
@@ -1,9 +1,9 @@
 'use strict';
 
+const common = require('../common');
 const fs = require('fs');
 const path = require('path');
 const assert = require('assert');
-const common = require('../common');
 const fixtures = path.join(__dirname, '..', 'fixtures');
 
 // Basic usage tests.
@@ -19,8 +19,60 @@ assert.throws(function() {
   fs.watchFile(new Object(), function() {});
 }, /Path must be a string/);
 
-// Test ENOENT. Should fire once.
-const enoentFile = path.join(fixtures, 'empty', 'non-existent-file');
+const enoentFile = path.join(fixtures, 'non-existent-file');
+const expectedStatObject = new fs.Stats(
+    0,                                        // dev
+    0,                                        // mode
+    0,                                        // nlink
+    0,                                        // uid
+    0,                                        // gid
+    0,                                        // rdev
+    common.isWindows ? undefined : 0,         // blksize
+    0,                                        // ino
+    0,                                        // size
+    common.isWindows ? undefined : 0,         // blocks
+    Date.UTC(1970, 0, 1, 0, 0, 0),            // atime
+    Date.UTC(1970, 0, 1, 0, 0, 0),            // mtime
+    Date.UTC(1970, 0, 1, 0, 0, 0),            // ctime
+    Date.UTC(1970, 0, 1, 0, 0, 0)             // birthtime
+);
+
+function removeTestFile() {
+  try {
+    fs.unlinkSync(enoentFile);
+  } catch (ex) {
+    if (ex.code !== 'ENOENT') {
+      throw ex;
+    }
+  }
+}
+
+// Make sure that the file does not exist, when the test starts
+removeTestFile();
+
+// If the file initially didn't exist, and gets created at a later point of
+// time, the callback should be invoked again with proper values in stat object
+var fileExists = false;
+
 fs.watchFile(enoentFile, common.mustCall(function(curr, prev) {
-  fs.unwatchFile(enoentFile);
-}));
+  if (!fileExists) {
+    // If the file does not exist, all the fields should be zero and the date
+    // fields should be UNIX EPOCH time
+    assert.deepStrictEqual(curr, expectedStatObject);
+    assert.deepStrictEqual(prev, expectedStatObject);
+    // Create the file now, so that the callback will be called back once the
+    // event loop notices it.
+    fs.closeSync(fs.openSync(enoentFile, 'w'));
+    fileExists = true;
+  } else {
+    // If the ino (inode) value is greater than zero, it means that the file is
+    // present in the filesystem and it has a valid inode number.
+    assert(curr.ino > 0);
+    // As the file just got created, previous ino value should be lesser than
+    // or equal to zero (non-existent file).
+    assert(prev.ino <= 0);
+    // Stop watching the file and delete it
+    fs.unwatchFile(enoentFile);
+    removeTestFile();
+  }
+}, 2));