Upgrade the Graphics Test Framework package to version 9

Upgrade your existing Graphics Test Framework project from version 8.x to version 9.x.

For more information, refer to what's new in version 9.0.

Replace [UseGraphicsTestCases] and [CodeBasedGraphicsTest]

A Graphics Test is now an NUnit Test that has a corresponding GraphicsTestCase, and one or more ReferenceImage images.

Follow these steps:

  1. Replace [UseGraphicsTestCases] with [SceneGraphicsTest] to surface a GraphicsTestCase in the results window in the Unity Editor.

  2. Replace [CodeBasedGraphicsTest] with [GraphicsTest].

For example, in version 8 code:

[Test, CodeBasedGraphicsTest("Assets/ReferenceImages")]
public void YourTest_WithTestCase_ExpectedResult()
{ }

In version 9 code:

[Test, GraphicsTest]
public void YourTest_WithTestCase_ExpectedResult(GraphicsTestCase testCase)
{ }

Note: Paths for reference images have moved from the parameters of CodeBasedGraphicsTest to the new Graphics Test Build Settings asset. For more information refer to Graphics Test Build Settings Inspector window reference.

Replace UseGraphicsTestCasesAttribute with SceneGraphicsTestAttribute

The UseGraphicsTestCasesAttribute API is now deprecated, and the Graphics Test Framework no longer automatically includes scenes from your build settings.

Use SceneGraphicsTestAttribute instead, which extends GraphicsTestAttribute. You must also now provide the paths to test scenes explicitly in the attribute parameters. You can add more than one path.

For example, in version 8:

[UnityTest, UseGraphicsTestCases("Assets/ReferenceImages")]
public void YourTest_WithTestCase_ExpectedResult(GraphicsTestCase testCase)
{ }

In version 9:

[UnityTest, SceneGraphicsTest("Assets/Scenes")]
public void YourTest_WithTestCase_ExpectedResult(SceneGraphicsTestCase testCase)
{ }

For more information, refer to Write a scene test and Customize a test.

Note: Paths for reference images have moved from the parameters of CodeBasedGraphicsTest to the new Graphics Test Build Settings asset. For more information refer to Graphics Test Build Settings Inspector window reference.

Replace ReferenceImagePathLog with ReferenceImage.LoadMessage

The load message of a reference image of a test case is now stored in the new ReferenceImage object. To update your project, replace ReferenceImagePathLog with ReferenceImage.LoadMessage. For example, testCase.ReferenceImagePathLog becomes testCase.ReferenceImage.LoadMessage.

Replace the Test Filters asset with the [IgnoreGraphicsTest] attribute

Follow these steps to upgrade your tests with the new [IgnoreGraphicsTest] attribute:

  1. Select a Test Filters asset to open its Inspector window.
  2. Select Convert Filters to Attributes. Unity lists an [IgnoreGraphicsTest] attribute for each filter.
  3. Copy the new attributes, then paste them at the top of your test method.
  4. Verify Unity runs the same number of tests.

To make it clearer which tests aren't running, ignored tests are no longer excluded from the test run. Instead they run and have a status of ignored.

Remove SetupGraphicsTestCases pre-build setup steps

The framework now automatically runs a pre-build setup step for any test with a GraphicsTestAttribute attribute or one of its children.

If you use a custom test build pipeline, use a Graphics Test Build Settings asset and disable Auto Build Test Cases. This step isn't necessary for most projects.

To add more code before a test, refer to Add your own code before a test.

Replace UseGraphicsTestCasesAttribute and TestUtils with GraphicsTestPlatform

Use the following APIs in version 9:

Replace deprecated APIs

Replace the following deprecated APIs with their new equivalents:

Replace removed APIs

Replace the following removed APIs with their new equivalents:

Remove APIs

The following APIs are no longer available:

  • TestResultWindow, ReferenceImageAnalyzerWindow, GraphicsTestSettingsWindow are replaced by the Graphics Tests window.
  • EditorUtils and TestUtils classes have moved to dedicated utility classes.

Additional resources