Dynamo Package Testing With the Revit Test Framework (RTF)

This document provides a step-by-step procedure for creating a Visual Studio project which is properly configured for testing against Dynamo on Revit. It is assumed that the reader of this document is writing a package for Dynamo for Revit and that their test assemblies will be in a folder that is NOT Dynamo's core directory. The test assemblies built following these procedures are compatible with the Revit Test Framework (RTF). More information about RTF can be found in the RTF repository.

Step 1: Create a Solution and a Project

The testing configuration described on this page allows you to create your own solution and project files, and your own output directory. You do not have to build into one of the Dynamo directories. Create a new solution or open an existing solution and create a new 'Class Library' project in Visual Studio.

Step 1a (Optional) : Create a Build Target to Make a Package

For instructions on how to setup your project directory and build tasks to generate a package when building your project, see Building a Package for Dynamo in Visual Studio.

Step 2: Create a Properties File

Using a text editor, create a .props file for your project, if you don't already have one. The properties file will be used to set environment variables that will help to configure your project environment when the project is loaded in Visual Studio.

An example properties file looks like this:

<?xml version="1.0" encoding="utf-8"?>
<Project DefaultTargets="Build" ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup Condition="'$(Configuration)|$(Platform)' == 'Debug|AnyCPU'">
    <VisualStudioVersion Condition="'$(VisualStudioVersion)' == ''">10.0</VisualStudioVersion>
    <OutputPath Condition="'$(OutputPath)' == ''">$(SolutionDir)..\bin\$(Platform)\$(Configuration)</OutputPath>
    <NunitPath Condition="'$(NunitPath)' == ''">$(SolutionDir)..\extern\NUnit</NunitPath>
    <REVIT_API Condition="'$(REVIT_API)' == ''">C:\Program Files\Autodesk\Revit Architecture 2015</REVIT_API>
    <DYNAMO_API Condition="'$(DYNAMO_API)' == ''">..\..\Dynamo\bin\AnyCPU\Debug</DYNAMO_API>
    <REVIT_VERSION>Revit_2015</REVIT_VERSION>
    <BaseIntermediateOutputPath>$(OutputPath)\int\</BaseIntermediateOutputPath>
    <DebugSymbols>true</DebugSymbols>
    <DebugType>full</DebugType>
    <Optimize>false</Optimize>
    <DefineConstants>DEBUG;TRACE</DefineConstants>
    <ErrorReport>prompt</ErrorReport>
    <WarningLevel>4</WarningLevel>
  </PropertyGroup>
  <PropertyGroup Condition="'$(Configuration)|$(Platform)' == 'Release|AnyCPU'">
    <VisualStudioVersion Condition="'$(VisualStudioVersion)' == ''">10.0</VisualStudioVersion>
    <OutputPath Condition="'$(OutputPath)' == ''">$(SolutionDir)..\bin\$(Platform)\$(Configuration)</OutputPath>
    <NunitPath Condition="'$(NunitPath)' == ''">$(SolutionDir)..\extern\NUnit</NunitPath>
    <REVIT_API Condition="'$(REVIT_API)' == ''">C:\Program Files\Autodesk\Revit Architecture 2015</REVIT_API>
    <DYNAMO_API Condition="'$(DYNAMO_API)' == ''">..\..\Dynamo\bin\AnyCPU\Debug</DYNAMO_API>
    <REVIT_VERSION>Revit_2015</REVIT_VERSION>
    <BaseIntermediateOutputPath>$(OutputPath)\int\</BaseIntermediateOutputPath>
    <DebugType>pdbonly</DebugType>
    <Optimize>true</Optimize>
    <DefineConstants>TRACE</DefineConstants>
    <ErrorReport>prompt</ErrorReport>
    <WarningLevel>4</WarningLevel>
  </PropertyGroup>
</Project>

• REVIT_API - This is the folder where RevitAPI.dll is located.
• DYNAMO_API - This is the folder where DynamoCore.dll is located.
• REVIT_VERSION - This is the name of the sub-folder in the Dynamo build directory from which you will reference revit-based dependencies. The value supplied here should correlate to the value of REVIT_API specified. The example above shows a configuration based on Revit 2015.

Add a reference to this properties file at the top of your .csproj file:

...
<ImportGroup Label="PropertySheets">
 <Import Project="$(SolutionDir)/Config/CS.props" />
</ImportGroup>
...

The properties file can be located anywhere, but it is recommended that you put it in a directory adjacent to the solution file so that other projects in the solution can access it as well. Above, we're referencing our file CS.props from a Config directory in the solution's directory.

Step 3: Create a Startup Script

Creating a script to start Visual Studio and load your solution, setting the correct environment variable values, is easy, and guarantees that your environment will always be configured correctly at startup. A simple .bat file which does this looks like this:

set DYNAMO_API=C:\Users\Joe\Documents\GitHub\Dynamo\bin\AnyCPU\Debug
set REVIT_API=C:\Program Files\Autodesk\Revit Architecture 2015
set REVIT_VERSION=Revit_2015
"C:\Program Files (x86)\Microsoft Visual Studio 11.0\Common7\IDE\devenv.exe" "MyAwesomeDynamoSolution.sln"

The environment variables are set as described above and Visual Studio is started specifying the name of your solution. You can create multiple start-up scripts representing multiple configurations.

Step 4: Reference the Required Assemblies for Testing

In order to test against Dynamo, your test fixture classes will need to derive from one of several test base classes. Referencing these assemblies and ensuring that you get the right versions requires the following steps:

• Add the following assemblies to as references to your project to get the required base classes. When these assemblies are referenced, they will be set to CopyLocal=true by default.
  • SystemTestServices.dll - This assembly is required for RevitTestServices.dll which you'll load in the next step.
  • RevitTestServices.dll - This assembly contains the base classes for Revit testing, RevitSystemTestBase and RevitNodeTestBase
  • RevitTestFrameworkTypes.dll - This assembly, provided by RTF, contains the TestModelAttribute, which is used to specify a Revit model to open when the test runs.
  • For system testing:
  • DynamoCore.dll - This assembly contains Dynamo's core model.
• For all of these assemblies, turn CopyLocal=False so these assemblies (and their dependencies) are not copied to your testing directory.
• Add the directories of these assemblies to RTF's AdditionalResolutionDirectories property. This will allow RTF's assembly resolver to locate necessary referenced assemblies at run-time. This can be done through RTF's UI by specifying a ';' delimited list of directory paths in the "Additional Resolution Directories" box. This enables RTF to use reflection-only assembly loading to interrogate your testing assembly for tests. With reflection-only loading the assemblies will not be locked and you'll be able to rebuild your test assembly with RT still running.

Step 5: Write a Test

using NUnit.Framework;
using RevitTestServices;
using RTF.Framework;

namespace Tests
{
    [SetUp]
    public void Setup()
    {
        // Set the working directory. This will allow you to use the OpenAndRunDynamoDefinition method,
        // specifying a relative path to the .dyn file you want to test.

        var asmDirectory = Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location);
        workingDirectory = Path.GetFullPath(Path.Combine(asmDirectory, @"..\..\..\exampleFiles"));
    }  

    [TestFixture]
    public class SystemTestExample : RevitSystemTestBase
    {
        [Test, TestModel(@".\Models\Test.rvt")]
        public void Location()
        {
            OpenAndRunDynamoDefinition(@".\test.dyn");

            // Your test logic goes here.
        }
    }
}

• The TestModel attribute is supplied by RTF and allows you to specify a Revit model to open when the test session starts. This path is relative to the WorkingDirectory specified in the RTF interface or on the RTF command line.
• The OpenAndRunDynamoDefinition method is provided by the SystemTestBase class. It opens and runs the Dynamo definition that you've supplied, relative to the workingDirectory that you defined in the RevitTestConfiguration.xml.

The example provided above only opens and runs a Dynamo definition, asserting that now exception is thrown. Further test logic will need to be added to your tests to verify that your graph is performing as expected. Many examples of system testing logic and utility methods provided for this purpose can be found in the DynamoCoreUITests project in the Dynamo repository.

Step 6: Update your Project File to Use Environment Variables

Edit your .csproj file, so that the referenced paths of the assemblies use the environment variables defined in your properties file. Visual Studio will, by default, make all paths to referenced assemblies relative to the project directory. This step is optional, but editing your project file to use your environment variables will allow you to easily reconfigure you project's references and take advantage of start-up scripts.

Before:

...
<Reference Include="DynamoCore">
      <HintPath>..\..\..\Dynamo\bin\AnyCPU\Debug\DynamoCore.dll</HintPath>
</Reference>
...
<Reference Include="RevitTestServices">
      <HintPath>..\..\..\Dynamo\bin\AnyCPU\Debug\Revit_2015\RevitTestServices.dll</HintPath>
</Reference>
...

After:

<Reference Include="DynamoCore">
      <HintPath>$(DYNAMO_API)\DynamoCore.dll</HintPath>
</Reference>
...
<Reference Include="RevitTestServices">
      <HintPath>$(DYNAMO_API)\$(REVIT_VERSION)\RevitTestServices.dll</HintPath>
</Reference>