test_runner: add t.assert.fileSnapshot()

This commit adds a t.assert.fileSnapshot() API to the test runner. This is similar to how snapshot tests work in core, as well as userland options such as toMatchFileSnapshot().

Author: cjihrig

doc/api/test.md

@@ -3255,6 +3255,43 @@ test('test', (t) =>{
 });
 ```
 
+#### `context.assert.fileSnapshot(value, path[, options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+*`value`{any} A value to serialize to a string. If Node.js was started with
+ the [`--test-update-snapshots`][] flag, the serialized value is written to
+`path`. Otherwise, the serialized value is compared to the contents of the
+ existing snapshot file.
+*`path`{string} The file where the serialized `value` is written.
+*`options`{Object} Optional configuration options. The following properties
+ are supported:
+*`serializers`{Array} An array of synchronous functions used to serialize
+`value` into a string. `value` is passed as the only argument to the first
+ serializer function. The return value of each serializer is passed as input
+ to the next serializer. Once all serializers have run, the resulting value
+ is coerced to a string. **Default:** If no serializers are provided, the
+ test runner's default serializers are used.
+
+This function serializes `value` and writes it to the file specified by `path`.
+
+```js
+test('snapshot test with default serialization', (t) =>{
+t.assert.fileSnapshot({value1:1, value2:2 }, './snapshots/snapshot.json');
+});
+```
+
+This function differs from `context.assert.snapshot()` in the following ways:
+
+* The snapshot file path is explicitly provided by the user.
+* Each snapshot file is limited to a single snapshot value.
+* No additional escaping is performed by the test runner.
+
+These differences allow snapshot files to better support features such as syntax
+highlighting.
+
 #### `context.assert.snapshot(value[, options])`
 
 <!-- YAML

lib/internal/test_runner/snapshot.js

@@ -23,6 +23,7 @@ const{
  validateArray,
  validateFunction,
  validateObject,
+ validateString,
 }=require('internal/validators');
 const{ strictEqual }=require('assert');
 const{ mkdirSync, readFileSync, writeFileSync }=require('fs');
@@ -109,16 +110,7 @@ class SnapshotFile{
 }
 this.loaded=true;
 }catch(err){
-letmsg=`Cannot read snapshot file '${this.snapshotFile}.'`;
-
-if(err?.code==='ENOENT'){
-msg+=` ${kMissingSnapshotTip}`;
-}
-
-consterror=newERR_INVALID_STATE(msg);
-error.cause=err;
-error.filename=this.snapshotFile;
-throwerror;
+throwReadError(err,this.snapshotFile);
 }
 }
 
@@ -132,11 +124,7 @@ class SnapshotFile{
 mkdirSync(dirname(this.snapshotFile),{__proto__: null,recursive: true});
 writeFileSync(this.snapshotFile,output,'utf8');
 }catch(err){
-constmsg=`Cannot write snapshot file '${this.snapshotFile}.'`;
-consterror=newERR_INVALID_STATE(msg);
-error.cause=err;
-error.filename=this.snapshotFile;
-throwerror;
+throwWriteError(err,this.snapshotFile);
 }
 }
 }
@@ -171,21 +159,18 @@ class SnapshotManager{
 
 serialize(input,serializers=serializerFns){
 try{
-letvalue=input;
-
-for(leti=0;i<serializers.length;++i){
-constfn=serializers[i];
-value=fn(value);
-}
-
+constvalue=serializeValue(input,serializers);
 return`\n${templateEscape(value)}\n`;
 }catch(err){
-consterror=newERR_INVALID_STATE(
-'The provided serializers did not generate a string.',
-);
-error.input=input;
-error.cause=err;
-throwerror;
+throwSerializationError(input,err);
+}
+}
+
+serializeWithoutEscape(input,serializers=serializerFns){
+try{
+returnserializeValue(input,serializers);
+}catch(err){
+throwSerializationError(input,err);
 }
 }
 
@@ -222,6 +207,80 @@ class SnapshotManager{
 }
 };
 }
+
+createFileAssert(){
+constmanager=this;
+
+returnfunctionfileSnapshotAssertion(actual,path,options=kEmptyObject){
+validateString(path,'path');
+validateObject(options,'options');
+const{
+ serializers =serializerFns,
+}=options;
+validateFunctionArray(serializers,'options.serializers');
+constvalue=manager.serializeWithoutEscape(actual,serializers);
+
+if(manager.updateSnapshots){
+try{
+mkdirSync(dirname(path),{__proto__: null,recursive: true});
+writeFileSync(path,value,'utf8');
+}catch(err){
+throwWriteError(err,path);
+}
+}else{
+letexpected;
+
+try{
+expected=readFileSync(path,'utf8');
+}catch(err){
+throwReadError(err,path);
+}
+
+strictEqual(value,expected);
+}
+};
+}
+}
+
+functionthrowReadError(err,filename){
+letmsg=`Cannot read snapshot file '${filename}.'`;
+
+if(err?.code==='ENOENT'){
+msg+=` ${kMissingSnapshotTip}`;
+}
+
+consterror=newERR_INVALID_STATE(msg);
+error.cause=err;
+error.filename=filename;
+throwerror;
+}
+
+functionthrowWriteError(err,filename){
+constmsg=`Cannot write snapshot file '${filename}.'`;
+consterror=newERR_INVALID_STATE(msg);
+error.cause=err;
+error.filename=filename;
+throwerror;
+}
+
+functionthrowSerializationError(input,err){
+consterror=newERR_INVALID_STATE(
+'The provided serializers did not generate a string.',
+);
+error.input=input;
+error.cause=err;
+throwerror;
+}
+
+functionserializeValue(value,serializers){
+letv=value;
+
+for(leti=0;i<serializers.length;++i){
+constfn=serializers[i];
+v=fn(v);
+}
+
+returnv;
 }
 
 functionvalidateFunctionArray(fns,name){

lib/internal/test_runner/test.js

@@ -128,6 +128,7 @@ function lazyAssertObject(harness){
 
 harness.snapshotManager=newSnapshotManager(harness.config.updateSnapshots);
 assertObj.set('snapshot',harness.snapshotManager.createAssert());
+assertObj.set('fileSnapshot',harness.snapshotManager.createFileAssert());
 }
 returnassertObj;
 }

test/fixtures/test-runner/snapshots/file-snapshots.js

@@ -0,0 +1,21 @@
+'use strict';
+const{ test }=require('node:test');
+
+test('snapshot file path is created',(t)=>{
+t.assert.fileSnapshot({baz: 9},'./foo/bar/baz/1.json');
+});
+
+test('test with plan',(t)=>{
+t.plan(2);
+t.assert.fileSnapshot({foo: 1,bar: 2},'2.json');
+t.assert.fileSnapshot(5,'3.txt');
+});
+
+test('custom serializers are supported',(t)=>{
+t.assert.fileSnapshot({foo: 1},'4.txt',{
+serializers: [
+(value)=>{returnvalue+'424242';},
+(value)=>{returnJSON.stringify(value);},
+]
+});
+});

test/parallel/test-runner-assert.js

@@ -10,7 +10,7 @@ test('expected methods are on t.assert', (t) =>{
 'strict',
 ];
 constassertKeys=Object.keys(assert).filter((key)=>!uncopiedKeys.includes(key));
-constexpectedKeys=['snapshot'].concat(assertKeys).sort();
+constexpectedKeys=['snapshot','fileSnapshot'].concat(assertKeys).sort();
 assert.deepStrictEqual(Object.keys(t.assert).sort(),expectedKeys);
 });
 

test/parallel/test-runner-snapshot-file-tests.js

@@ -0,0 +1,82 @@
+'use strict';
+constcommon=require('../common');
+constfixtures=require('../common/fixtures');
+consttmpdir=require('../common/tmpdir');
+const{ suite, test }=require('node:test');
+
+tmpdir.refresh();
+
+suite('t.assert.fileSnapshot() validation',()=>{
+test('path must be a string',(t)=>{
+t.assert.throws(()=>{
+t.assert.fileSnapshot({},5);
+},/The"path"argumentmustbeoftypestring/);
+});
+
+test('options must be an object',(t)=>{
+t.assert.throws(()=>{
+t.assert.fileSnapshot({},'',null);
+},/The"options"argumentmustbeoftypeobject/);
+});
+
+test('options.serializers must be an array if present',(t)=>{
+t.assert.throws(()=>{
+t.assert.fileSnapshot({},'',{serializers: 5});
+},/The"options\.serializers"propertymustbeaninstanceofArray/);
+});
+
+test('options.serializers must only contain functions',(t)=>{
+t.assert.throws(()=>{
+t.assert.fileSnapshot({},'',{serializers: [()=>{},'']});
+},/The"options\.serializers\[1\]"propertymustbeoftypefunction/);
+});
+});
+
+suite('t.assert.fileSnapshot() update/read flow',()=>{
+constfixture=fixtures.path(
+'test-runner','snapshots','file-snapshots.js'
+);
+
+test('fails prior to snapshot generation',async(t)=>{
+constchild=awaitcommon.spawnPromisified(
+process.execPath,
+[fixture],
+{cwd: tmpdir.path},
+);
+
+t.assert.strictEqual(child.code,1);
+t.assert.strictEqual(child.signal,null);
+t.assert.match(child.stdout,/tests3/);
+t.assert.match(child.stdout,/pass0/);
+t.assert.match(child.stdout,/fail3/);
+t.assert.match(child.stdout,/Missingsnapshotscanbegenerated/);
+});
+
+test('passes when regenerating snapshots',async(t)=>{
+constchild=awaitcommon.spawnPromisified(
+process.execPath,
+['--test-update-snapshots',fixture],
+{cwd: tmpdir.path},
+);
+
+t.assert.strictEqual(child.code,0);
+t.assert.strictEqual(child.signal,null);
+t.assert.match(child.stdout,/tests3/);
+t.assert.match(child.stdout,/pass3/);
+t.assert.match(child.stdout,/fail0/);
+});
+
+test('passes when snapshots exist',async(t)=>{
+constchild=awaitcommon.spawnPromisified(
+process.execPath,
+[fixture],
+{cwd: tmpdir.path},
+);
+
+t.assert.strictEqual(child.code,0);
+t.assert.strictEqual(child.signal,null);
+t.assert.match(child.stdout,/tests3/);
+t.assert.match(child.stdout,/pass3/);
+t.assert.match(child.stdout,/fail0/);
+});
+});