UTFAnalyzers 1.4.3
dotnet add package UTFAnalyzers --version 1.4.3
NuGet\Install-Package UTFAnalyzers -Version 1.4.3
<PackageReference Include="UTFAnalyzers" Version="1.4.3"> <PrivateAssets>all</PrivateAssets> <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets> </PackageReference>
<PackageVersion Include="UTFAnalyzers" Version="1.4.3" />
<PackageReference Include="UTFAnalyzers"> <PrivateAssets>all</PrivateAssets> <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets> </PackageReference>
paket add UTFAnalyzers --version 1.4.3
#r "nuget: UTFAnalyzers, 1.4.3"
#:package UTFAnalyzers@1.4.3
#addin nuget:?package=UTFAnalyzers&version=1.4.3
#tool nuget:?package=UTFAnalyzers&version=1.4.3
UTF Analyzers
This package provides Roslyn analyzers to help you write safer unit tests with the Unity Test Framework. It diagnoses API usage that could cause Unity Editor freezes or runtime errors before running tests and suggests best practices.
Required
- Unity 2022.3.12f1 or later
Diagnostics
Baseline version
The analyzers diagnose against the Unity Test Framework package v1.4.6 as the baseline. UTF v1.4.6 is the last version you can update independently as a UPM package.
[!CAUTION]
Versions earlier than the baseline have bugs that these analyzers do not diagnose. Update to UTF v1.4.6 or later.
[!TIP]
Diagnostics remain even if the bug is fixed in UTF v1.5.0 or later. If the bug is fixed in the version you are using, suppress the diagnostic in your project via.editorconfigor.globalconfig.
Structure (UTF1xxx)
Rules about test method signatures and attribute combinations.
| Id | Title | Severity |
|---|---|---|
| UTF1001 | TestCase and TestCaseSource attributes are not supported on coroutine-style test methods | ❌ |
| UTF1002 | Task<TResult> is not supported as a test method return type | ❌ |
| UTF1003 | Pairwise, Sequential, and Combinatorial attributes are not supported on coroutine-style test methods | ❌ |
| UTF1004 | OneTimeSetUp and OneTimeTearDown attributes are not supported on async methods | ❌ |
| UTF1005 | Attributes implementing ICommandWrapper are not supported on async and coroutine-style test methods | ❌ |
| UTF1006 | Only Task is supported as an async test method return type | ❌ |
| UTF1007 | Only Task is supported as an async SetUp and TearDown method return type | ❌ |
| UTF1008 | Only IEnumerator is supported as the return type of methods with the UnityTest attribute | ❌ |
| UTF1009 | Only IEnumerator is supported as the return type of methods with the UnitySetUp, UnityTearDown, UnityOneTimeSetUp, and UnityOneTimeTearDown attributes | ❌ |
Assertion (UTF2xxx)
Rules about misuse of assertions and constraints.
| Id | Title | Severity |
|---|---|---|
| UTF2001 | Assert.ThrowsAsync, CatchAsync, and DoesNotThrowAsync are not supported | ❌ |
| UTF2002 | Async delegates are not supported as the actual value of Throws constraints, Assert.Throws, Assert.Catch, and Assert.DoesNotThrow | ❌ |
| UTF2003 | Async delegates are not supported as the actual value of the constraint model | ❌ |
| UTF2004 | Only TestDelegate is supported as the actual value of the AllocatingGCMemory constraint | ❌ |
| UTF2005 | DelayedConstraint is not supported | ❌ |
| UTF2006 | Property constraints, Ordered.By, and List.Map(...).Property look up properties by reflection that managed code stripping can remove | ℹ️ |
[!TIP]
If your project runs tests on the Player, raise the severity of UTF2006 to warning or higher. The default suggestion severity reports it only in the IDE, and the test fails only on the Player (see UTF2006).
Suppressor (UTF3xxx)
Suppressions of diagnostics reported by other analyzers that do not apply to Unity Test Framework.
| Id | Title |
|---|---|
| UTF3001 | Suppress NUnit2045 (Use Assert.Multiple) when Assert.Multiple is not available |
| UTF3002 | Suppress CS8618 (Non-nullable field or property is uninitialized) when the member is initialized in a UnitySetUp or UnityOneTimeSetUp method |
| UTF3003 | Suppress CA1001 (Types that own disposable fields should be disposable) on test fixtures with a UnityTearDown or UnityOneTimeTearDown method |
| UTF3004 | Suppress NUnit1028 (The non-test method is public) on UnitySetUp, UnityOneTimeSetUp, UnityTearDown, and UnityOneTimeTearDown methods |
| UTF3005 | Suppress CA1707 (Identifiers should not contain underscores) on test methods |
| UTF3006 | Suppress VSTHRD200 (Use Async suffix for async methods) on test methods |
Style (UTF4xxx)
Rules about code that works but is not recommended.
| Id | Title | Severity |
|---|---|---|
| UTF4001 | Test methods that wait for a condition must have a Timeout attribute | ❌ |
| UTF4002 | Waits for a condition in UnitySetUp, UnityTearDown, UnityOneTimeSetUp, UnityOneTimeTearDown, SetUp, and TearDown methods must have a time limit | ❌ |
| UTF4003 | Waiting for a condition without yielding or awaiting does not advance frames | ❌ |
| UTF4004 | Waiting for a fixed time in test, setup, and teardown methods is not recommended | ⚠️ |
| UTF4005 | MonoBehaviour classes in test assemblies should be hidden from the Add Component menu | ⚠️ |
| UTF4006 | Async Task test methods are recommended over coroutine-style test methods with the UnityTest attribute | ⚠️ |
| UTF4007 | Async Task SetUp and TearDown methods are recommended over coroutine-style methods with the UnitySetUp and UnityTearDown attributes | ⚠️ |
Extensions (UTF5xxx)
Rules for authors of custom attributes, constraints, and comparers.
| Id | Title | Severity |
|---|---|---|
| UTF5001 | ApplyToTest, ApplyToContext, and Wrap must not throw exceptions | ❌ |
| UTF5002 | Implementing IWrapTestMethod and IWrapSetUpTearDown is not recommended | ⚠️ |
| UTF5003 | Attributes implementing IOuterUnityTestAction must restrict their targets with AttributeUsage | ⚠️ |
| UTF5004 | Attributes implementing ITestAction must restrict their targets with AttributeUsage | ⚠️ |
Installation
This package is published to both UPM and NuGet. Choose one of the following.
Install UPM package via OpenUPM
- Open the Project Settings window (Editor > Project Settings) and select Package Manager tab
- Click + button under the Scoped Registries and enter the following settings:
- Name:
package.openupm.com - URL:
https://package.openupm.com - Scope(s):
com.nowsprinting
- Name:
- Open the Package Manager window (Window > Package Manager) and select My Registries tab
- Select UTF Analyzers and click the Install button
[!TIP]
You do not need to add a reference to the test assembly definition file (asmdef). Because it's configured via an assembly definition reference file (asmref) to apply across all test assemblies.
[!TIP]
The UPM package also includes the following:
- Unity Test Framework v1.4.6 (dependency)
- NUnit.Analyzers v3.9.0 (bundled)
UTFAnalyzers does not require either of these. If you do not need them, use the NuGet package instead.
Install NuGet package via NuGetForUnity
- Open the NuGetForUnity window via NuGet > Manage NuGet Packages
- Search "UTFAnalyzers" and click Install
License
MIT License
How to contribute
Open an issue or create a pull request.
Be grateful if you could label the PR as enhancement, bug, chore, and documentation.
See the autolabeler section in release-drafter settings for automatically labeling from the branch name.
How to development
Clone repo as a embedded package
Clone this repository as a submodule under the Packages/ directory in your project.
git submodule add git@github.com:nowsprinting/test-framework.analyzers.git Packages/com.nowsprinting.test-framework.analyzers
Run Tests
cd Packages/com.nowsprinting.test-framework.analyzers/UTF.Analyzers~
dotnet test
Build
cd Packages/com.nowsprinting.test-framework.analyzers/UTF.Analyzers~
dotnet build -c Release UTF.Analyzers
After the Release build, UTF.Analyzers.dll is automatically copied to Analyzers/UTF.Analyzers/.
Please commit the copied DLL; it will be distributed as part of the UPM package.
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.