Skip to content

Latest commit

 

History

History
636 lines (511 loc) · 18 KB

naming.md

File metadata and controls

636 lines (511 loc) · 18 KB
Raw

File Naming

Naming determines the file name for the .received. resulting .verified. files.

The format is

{Directory}/{TestClassName}.{TestMethodName}_{Parameters}_{UniqueFor1}_{UniqueFor2}_{UniqueForX}.verified.{extension}

Directory

The directory that contains the test. A custom directory can be used via UseDirectory:

var settings = new VerifySettings();
settings.UseDirectory("CustomDirectory");
await Verify("value", settings);

snippet source | anchor

await Verify("value")
    .UseDirectory("CustomDirectory");

snippet source | anchor

Will result in CustomDirectory/TypeName.MethodName.verified.txt.

The path provided can be absolute or relative to the directory that contains the test.

TestClassName

The class name that contains the test. A custom test name can be used via UseTypeName:

var settings = new VerifySettings();
settings.UseTypeName("CustomTypeName");
await Verify("value", settings);

snippet source | anchor

await Verify("value")
    .UseTypeName("CustomTypeName");

snippet source | anchor

Will result in CustomTypeName.MethodName.verified.txt.

TestMethodName

The test method name. A custom test name can be used via UseMethodName:

var settings = new VerifySettings();
settings.UseMethodName("CustomMethodName");
await Verify("value", settings);

snippet source | anchor

Will result in TestClass.CustomMethodName.verified.txt.

await Verify("value")
    .UseMethodName("CustomMethodNameFluent");

snippet source | anchor

Will result in TestClass.CustomMethodNameFluent.verified.txt.

Multiple calls to Verify

UseMethodName can also be used to allow multiple calls to Verify in the same method:

[Fact]
public async Task MultipleCalls()
{
    await Task.WhenAll(
        Verify("Value1")
            .UseMethodName("MultipleCalls_1"),
        Verify("Value1")
            .UseMethodName("MultipleCalls_2"));
}

snippet source | anchor

UseFileName

To fully control the {TestClassName}.{TestMethodName}_{Parameters} parts of the file use UseFileName:

var settings = new VerifySettings();
settings.UseFileName("CustomFileName");
await Verify("value", settings);

snippet source | anchor

Will result in CustomFileName.verified.txt.

await Verify("value")
    .UseFileName("CustomFileNameFluent");

snippet source | anchor

Will result in UseFileNameFluent.verified.txt.

Compatibility:

  • Not compatible with UseTypeName, UseMethodName, or UseParameters. An exception will be thrown if they are combined.
  • Can be used in combination with UseDirectory.
  • Can be used in combination with UniqueFor*.

Parameters

See Parameterised Tests.

UniqueFor

UniqueFor* allows for one or more delimiters to be added to the file name.

XUnit

[UsesVerify]
public class UniqueForSample
{
    [Fact]
    public Task Runtime()
    {
        var settings = new VerifySettings();
        settings.UniqueForRuntime();
        return Verify("value", settings);
    }

    [Fact]
    public Task RuntimeFluent()
    {
        return Verify("value")
            .UniqueForRuntime();
    }

    [Fact]
    public Task RuntimeAndVersion()
    {
        var settings = new VerifySettings();
        settings.UniqueForRuntimeAndVersion();
        return Verify("value", settings);
    }

    [Fact]
    public Task AssemblyConfiguration()
    {
        var settings = new VerifySettings();
        settings.UniqueForAssemblyConfiguration();
        return Verify("value", settings);
    }

    [Fact]
    public Task AssemblyConfigurationFluent()
    {
        return Verify("value")
            .UniqueForAssemblyConfiguration();
    }

    [Fact]
    public Task Architecture()
    {
        var settings = new VerifySettings();
        settings.UniqueForArchitecture();
        return Verify("value", settings);
    }

    [Fact]
    public Task ArchitectureFluent()
    {
        return Verify("value")
            .UniqueForArchitecture();
    }

    [Fact]
    public Task OSPlatform()
    {
        var settings = new VerifySettings();
        settings.UniqueForOSPlatform();
        return Verify("value", settings);
    }

    [Fact]
    public Task OSPlatformFluent()
    {
        return Verify("value")
            .UniqueForOSPlatform();
    }
}

snippet source | anchor

NUnit

[TestFixture]
public class UniqueForSample
{
    [Test]
    public Task Runtime()
    {
        var settings = new VerifySettings();
        settings.UniqueForRuntime();
        return Verify("value", settings);
    }

    [Test]
    public Task RuntimeFluent()
    {
        return Verify("value")
            .UniqueForRuntime();
    }

    [Test]
    public Task AssemblyConfiguration()
    {
        var settings = new VerifySettings();
        settings.UniqueForAssemblyConfiguration();
        return Verify("value", settings);
    }

    [Test]
    public Task AssemblyConfigurationFluent()
    {
        return Verify("value")
            .UniqueForAssemblyConfiguration();
    }

    [Test]
    public Task RuntimeAndVersion()
    {
        var settings = new VerifySettings();
        settings.UniqueForRuntimeAndVersion();
        return Verify("value", settings);
    }

    [Test]
    public Task RuntimeAndVersionFluent()
    {
        return Verify("value")
            .UniqueForRuntimeAndVersion();
    }

    [Test]
    public Task Architecture()
    {
        var settings = new VerifySettings();
        settings.UniqueForArchitecture();
        return Verify("value", settings);
    }

    [Test]
    public Task ArchitectureFluent()
    {
        return Verify("value")
            .UniqueForArchitecture();
    }

    [Test]
    public Task OSPlatform()
    {
        var settings = new VerifySettings();
        settings.UniqueForOSPlatform();
        return Verify("value", settings);
    }

    [Test]
    public Task OSPlatformFluent()
    {
        return Verify("value")
            .UniqueForOSPlatform();
    }
}

snippet source | anchor

Expecto

[<Tests>]
let uniqueTests =
  testTask "unique" {
    let settings = new VerifySettings()
    settings.UniqueForRuntime()
    do! Verifier.Verify("unique", "value1", settings)
  }

snippet source | anchor

MSTest

[TestClass]
public class UniqueForSample :
    VerifyBase
{
    [TestMethod]
    public Task Runtime()
    {
        var settings = new VerifySettings();
        settings.UniqueForRuntime();
        return Verify("value", settings);
    }

    [TestMethod]
    public Task RuntimeFluent()
    {
        return Verify("value")
            .UniqueForRuntime();
    }

    [TestMethod]
    public Task RuntimeAndVersion()
    {
        var settings = new VerifySettings();
        settings.UniqueForRuntimeAndVersion();
        return Verify("value", settings);
    }

    [TestMethod]
    public Task RuntimeAndVersionFluent()
    {
        return Verify("value")
            .UniqueForRuntimeAndVersion();
    }

    [TestMethod]
    public Task AssemblyConfiguration()
    {
        var settings = new VerifySettings();
        settings.UniqueForAssemblyConfiguration();
        return Verify("value", settings);
    }

    [TestMethod]
    public Task AssemblyConfigurationFluent()
    {
        return Verify("value")
            .UniqueForAssemblyConfiguration();
    }

    [TestMethod]
    public Task Architecture()
    {
        var settings = new VerifySettings();
        settings.UniqueForArchitecture();
        return Verify("value", settings);
    }

    [TestMethod]
    public Task ArchitectureFluent()
    {
        return Verify("value")
            .UniqueForArchitecture();
    }

    [TestMethod]
    public Task OSPlatform()
    {
        var settings = new VerifySettings();
        settings.UniqueForOSPlatform();
        return Verify("value", settings);
    }

    [TestMethod]
    public Task OSPlatformFluent()
    {
        return Verify("value")
            .UniqueForOSPlatform();
    }
}

snippet source | anchor

Result

For a project executed on both x64 and x86 that targets

<TargetFrameworks>netcoreapp3.0;net48</TargetFrameworks>

Will result in the following files being produced:

UniqueForSample.Runtime.Core.verified.txt
UniqueForSample.Runtime.Net.verified.txt
UniqueForSample.RuntimeAndVersion.Core3_0.verified.txt
UniqueForSample.RuntimeAndVersion.Net4_8.verified.txt
UniqueForSample.Architecture.X86.verified.txt
UniqueForSample.Architecture.X64.verified.txt

Extension

The default file extension is .txt. So the resulting verified file will be TestClass.TestMethod.verified.txt.

It can be overridden at two levels:

  • Method: Change the extension for the current test method.
  • Class: Change the extension all verifications in all test methods for a test class.

Usage:

[UsesVerify]
public class ExtensionSample
{
    VerifySettings classLevelSettings;

    public ExtensionSample()
    {
        classLevelSettings = new();
        classLevelSettings.UseExtension("json");
    }

    [Fact]
    public Task AtMethod()
    {
        var settings = new VerifySettings(classLevelSettings);
        settings.UseExtension("xml");
        return Verify(
            target: @"
<note>
  <to>Joe</to>
  <from>Kim</from>
  <heading>Reminder</heading>
</note>",
            settings: settings);
    }

    [Fact]
    public Task AtMethodFluent()
    {
        return Verify(
                target: @"
<note>
  <to>Joe</to>
  <from>Kim</from>
  <heading>Reminder</heading>
</note>",
                settings: classLevelSettings)
            .UseExtension("xml");
    }

    [Fact]
    public Task SharedClassLevelSettings()
    {
        return Verify(
            target: @"
{
  fruit: 'Apple',
  size: 'Large',
  color: 'Red'
}",
            settings: classLevelSettings);
    }
}

snippet source | anchor

Result in two files:

{
  fruit: 'Apple',
  size: 'Large',
  color: 'Red'
}

snippet source | anchor

<note>
  <to>Joe</to>
  <from>Kim</from>
  <heading>Reminder</heading>
</note>

snippet source | anchor

NamerRuntimeAndVersion

To access the current Namer Runtime or RuntimeAndVersion strings use:

Debug.WriteLine(Namer.Runtime);
Debug.WriteLine(Namer.RuntimeAndVersion);

snippet source | anchor

DerivePathInfo

DerivePathInfo allows the storage directory of .verified. files to be customized based on the current context. The contextual parameters are parameters passed are as follows:

  • sourceFile: The full path to the file that the test existed in at compile time.
  • projectDirectory: The directory that the project existed in at compile time.
  • type: The class the test method exists in.
  • method: The test method.

For example to place all .verified. files in a {ProjectDirectory}\Snapshots the following could be used:

VerifierSettings.DerivePathInfo(
    (sourceFile, projectDirectory, type, method) =>
    {
        return new(
            directory: Path.Combine(projectDirectory, "Snapshots"),
            typeName: type.Name,
            methodName: method.Name);
    });

snippet source | anchor

Return null to any of the values to use the standard behavior. The returned path can be relative to the directory sourceFile exists in.

DerivePathInfo can also be useful when deriving the storage directory on a build server

A DerivePathInfo convention can be shipped as a NuGet, for example Spectre.Verify.Extensions which adds an attribute driven file naming convention to Verify.

Default DerivePathInfo

static DerivePathInfo derivePathInfo = (sourceFile, projectDirectory, type, method) =>
{
    static string GetTypeName(Type type)
    {
        if (type.IsNested)
        {
            return $"{type.ReflectedType!.Name}.{type.Name}";
        }

        return type.Name;
    }

    var typeName = GetTypeName(type);

    return new(Path.GetDirectoryName(sourceFile)!, typeName, method.Name);
};

snippet source | anchor

DisableRequireUniquePrefix

Snapshot file names have to be unique. If a duplicate name is used, then an exception will be throw. This is mostly caused by a conflicting combination of VerifierSettings.DerivePathInfo(), UseMethodName.UseDirectory(), UseMethodName.UseTypeName(), and UseMethodName.UseMethodName(). If that's not the case, and having multiple identical prefixes is acceptable, then call VerifierSettings.DisableRequireUniquePrefix() to disable this uniqueness validation