Testably.Abstractions.Migration
0.5.0
Prefix Reserved
dotnet add package Testably.Abstractions.Migration --version 0.5.0
NuGet\Install-Package Testably.Abstractions.Migration -Version 0.5.0
<PackageReference Include="Testably.Abstractions.Migration" Version="0.5.0"> <PrivateAssets>all</PrivateAssets> <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets> </PackageReference>
<PackageVersion Include="Testably.Abstractions.Migration" Version="0.5.0" />
<PackageReference Include="Testably.Abstractions.Migration"> <PrivateAssets>all</PrivateAssets> <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets> </PackageReference>
paket add Testably.Abstractions.Migration --version 0.5.0
#r "nuget: Testably.Abstractions.Migration, 0.5.0"
#:package Testably.Abstractions.Migration@0.5.0
#addin nuget:?package=Testably.Abstractions.Migration&version=0.5.0
#tool nuget:?package=Testably.Abstractions.Migration&version=0.5.0
Testably.Abstractions.Migration
A Roslyn analyzer with a code fix that migrates System.IO.Abstractions (TestableIO) usage of MockFileSystem and MockFileData to the Testably.Abstractions MockFileSystem API. Drop the package into a project that uses TestableIO.System.IO.Abstractions.TestingHelpers: the code fix rewrites the supported patterns, and the analyzer reports the rest so you can address them by hand.
The documentation is at docs.testably.org/Abstractions/migration-from-testableio/Migration.
Installation
The migration package is a one-shot development tool: install it, migrate, then uninstall. It ships only the analyzer and the code fix, no runtime code, and is marked as a DevelopmentDependency so it never flows transitively to consumers of your test project.
Because the package does not pull Testably.Abstractions.Testing transitively, you must reference it yourself in the project being migrated. Otherwise the rewritten call sites would compile while the migration package is installed but stop compiling the moment you remove it.
dotnet add package Testably.Abstractions.Testing
dotnet add package Testably.Abstractions.Migration
How it works
The analyzer reports every call site with the single diagnostic id TestablyM001. Patterns without an automatic rewrite are reported as well, so you can locate them; the code fix just offers no rewrite for them.
| Diagnostic | Source library | Code fix title |
|---|---|---|
TestablyM001 |
TestableIO | Migrate System.IO.Abstractions MockFileSystem to Testably.Abstractions |
What the code fix rewrites, with examples and the supported constructs, is described in Migrating from TestableIO.
Recommended workflow
- Reference the target library. Add
Testably.Abstractions.Testingto the project you want to migrate (see Installation). ExistingTestableIO.System.IO.Abstractions.TestingHelpersusage keeps compiling side-by-side. - Install the migration package. Every construct the code fix supports and every construct that needs manual review is reported as warning
TestablyM001. - Apply the code fix in your IDE (Visual Studio, Rider, VS Code with C# Dev Kit), where one fix migrates the whole file and Fix all occurrences migrates the project or solution, or from the command line with
dotnet format analyzers --diagnostics TestablyM001. - Address the call sites that need manual review. The code fix offers no rewrite for them, so they keep their warning; migrate each one by hand.
- Remove TestableIO and the migration package (see Removing the package).
Manual review
These call sites are flagged with TestablyM001 but have no automatic rewrite, either because Testably.Abstractions has no equivalent surface or because a safe rewrite would require flow analysis the analyzer does not perform. Address each one by hand.
| Pattern | Why manual |
|---|---|
MockFileData.AccessControl |
Use SetAccessControl from the AccessControl companion package; to deny access, register a strategy with WithAccessControlStrategy. |
MockFileData.AllowedFileShare |
Testably.Abstractions honors the FileShare a file was opened with; keep a stream with the restricted share open instead. |
MockFileData.UnixMode |
Use File.SetUnixFileMode; to enforce the permissions, register a strategy with WithUnixFileModeStrategy. |
new MockFileVersionInfo(...) |
Register the version information for a path pattern with WithFileVersionInfo. |
Subclassing MockFileSystem / MockFileData |
Inheritance contract differs in Testably.Abstractions. |
new MockFileData(MockFileData template) |
Copy-clone semantics differ; no Testably.Abstractions equivalent. |
Captured-reference MockFileData property access |
var data = fs.GetFile(path); data.Prop = … cannot be rewritten without local flow analysis. |
fs.AllPaths / AllFiles / AllDirectories / AllDrives |
Testably.Abstractions has no enumeration properties; the natural replacements need a root or drive scope the analyzer cannot infer. |
fs.MockTime(Func<DateTime>) |
TestableIO calls the delegate per timestamp request; Testably.Abstractions installs a fixed-then-mutable MockTimeSystem at construction. No observably-equivalent automatic rewrite for arbitrary delegates. |
fs.AddFileFromEmbeddedResource(...) |
Testably.Abstractions exposes only a bulk InitializeEmbeddedResourcesFromAssembly with path-style matching; the single-file mapping is not safe to automate. |
Suppressing the diagnostic
If you choose not to migrate a particular call site, suppress TestablyM001 per usage with the standard mechanisms:
#pragma warning disable TestablyM001
MockFileSystem fs = new MockFileSystem();
#pragma warning restore TestablyM001
or via an .editorconfig entry scoped to the file or folder:
[**/Legacy/**.cs]
dotnet_diagnostic.TestablyM001.severity = none
Removing the package
Once the analyzer is quiet, remove TestableIO.System.IO.Abstractions.TestingHelpers (or System.IO.Abstractions.TestingHelpers, the older package id that forwards to it), and then the migration package, which only adds analyzer overhead from here on:
dotnet remove package TestableIO.System.IO.Abstractions.TestingHelpers
dotnet remove package Testably.Abstractions.Migration
Testably.Abstractions.Testing stays in the project; that is the library the tests now depend on.
Learn more about Target Frameworks and .NET Standard.
This package has no dependencies.
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.