Repository files navigation

An xUnit runner for Autodesk Revit.

Check out our blog post on this 👉https://speckle.systems/blog/xunitrevit !

xUnitRevit usesspeckle.xunit.runner.wpf which is a fork ofxunit.runner.wpf, it allows to easily develop and run xUnit tests in Revit.

Many thanks to all the developers of xunit and xunit.runner.wpf!

This repo is composed of 2 projects:

• xUnitRevitRunner: the actual Revit addin
• xUnitRevitUtils: a utility library to help pass Revit data to the test libraries when running the tests

There are very few steps required to create and run your fist unit tests with xUnitRevit:

1. create a copy of theconfig sample file and re-name the copy toconfig.json
2. follow the instructionshere to set up the config file
3. build/install xUnitRevitRunner
4. create a test library
5. start Revit, launch the xUnitRevitRunner addin and select the test library
6. done! Add a star ⭐ to our repo if it was useful 😉

After cloning this repo, all you need to do to run xUnitRevitRunner is to build the project corresponding to your revit version inDebug mode

This will build the project and copy its dlls to the Revit addin folder%appdata%\Autodesk\Revit\Addins.

You can also, similarly, build the project inRelease mode, and manually copy the built files fromxunit-Revit\Release.

Creating a test library is pretty straightforward, at least we tried to make it as simple as possible!

Just follow the steps below for Revit 2021:

• create a new .net framework class library project (4.8 for Revit 2021)
• add the NuGet packages
  • xunit
  • xUnitRevitUtils.2021

That's it, now we can start adding our tests.

To do almost anything with the Revit API you need a reference to the active Document, and this is where xUnitRevitUtils comes into play, with itsxru static class. The code below shows how we can use it to get a list of Walls and check their properties.

Full code :https://github.com/Speckle-Next/xUnitRevit/blob/master/SampleLibrary/SampleTest.cs

[Fact]publicvoidWallsHaveVolume(){vartestModel=GetTestModel("walls.rvt");vardoc=xru.OpenDoc(testModel);varwalls=newFilteredElementCollector(doc).WhereElementIsNotElementType().OfCategory(BuiltInCategory.OST_Walls).ToElements();foreach(varwallinwalls){varvolumeParam=wall.get_Parameter(BuiltInParameter.HOST_VOLUME_COMPUTED);Assert.NotNull(volumeParam);Assert.True(volumeParam.AsDouble()>0);}doc.Close(false);}

To be able to share context between tests, xUnits usesfixtures. We can use fixtures for instance, to open a Revit model only once and use it across multiple tests.

Let's see an example, full code:https://github.com/Speckle-Next/xUnitRevit/blob/master/SampleLibrary/TestWithFixture.cs

publicclassDocFixture:IDisposable{publicDocumentDoc{get;set;}publicIList<Element>Walls{get;set;}publicDocFixture(){vartestModel=Utils.GetTestModel("walls.rvt");Doc=xru.OpenDoc(testModel);Walls=newFilteredElementCollector(Doc).WhereElementIsNotElementType().OfCategory(BuiltInCategory.OST_Walls).ToElements();}publicvoidDispose(){}}publicclassTestWithFixture:IClassFixture<DocFixture>{DocFixturefixture;publicTestWithFixture(DocFixturefixture){this.fixture=fixture;}[Fact]publicvoidCountWalls(){Assert.Equal(4,fixture.Walls.Count);}[Fact]publicvoidWallOffset(){varwall=fixture.Doc.GetElement(newElementId(346573));varparam=wall.get_Parameter(BuiltInParameter.WALL_BASE_OFFSET);varbaseOffset=UnitUtils.ConvertFromInternalUnits(param.AsDouble(),param.DisplayUnitType);Assert.Equal(2000,baseOffset);}}

Another feature of xUnitRevitUtils is that it offers a helper method to run Transactions, so you don't have to worry about that 🤯! Check the example below:https://github.com/Speckle-Next/xUnitRevit/blob/master/SampleLibrary/TestWithFixture.cs

[Fact]publicvoidMoveWallsUp(){varwalls=fixture.Walls.Where(x=>x.Id.IntegerValue!=346573);xru.RunInTransaction(()=>{foreach(varwallinwalls){varparam=wall.get_Parameter(BuiltInParameter.WALL_BASE_OFFSET);varbaseOffset=UnitUtils.ConvertToInternalUnits(2000,param.DisplayUnitType);param.Set(baseOffset);}},fixture.Doc).Wait();// Important! Wait for action to finishforeach(varwallinwalls){varparam=wall.get_Parameter(BuiltInParameter.WALL_BASE_OFFSET);varbaseOffset=UnitUtils.ConvertFromInternalUnits(param.AsDouble(),param.DisplayUnitType);Assert.Equal(2000,baseOffset);}}

We've added a couple of optional settings for lazy developers like me, to help speed up frequent testing of a test library. You'll see aconfig_sample.json in the root of the project. Copy the file and rename the copy toconfig.json and set it tocopy local = true. You'll then be able to configure

• startupAssemblies: if set, automatically loads a set of assemblies when xUnitRevit starts
• autoStart: if true, automatically opens the xUnitRevit window after Revit loads

Dlls loaded by xUnitRevit are loaded in Revit's AppDomain, and therefore it's not possible to recompile them until Revit is closed (even if you see an auto reload option in the UI). But don't despair, since Revit 2020 it's possible toedit & continue your code while debugging, so you won't have to restart Revit each time.

As for next steps, we're planning to add additional features to run xUnitRevit from a CI/CD routine.

Stay tuned!

xUnitRevit was developed to help us develop a better Speckle 2.0 connector for Revit, we hope you'll find it useful too.

Want to suggest a feature, report a bug, submit a PR? Please open an issue to discuss first!

Please make sure you read thecontribution guidelines andcode of conduct for an overview of the practices we try to follow.

The Speckle Community hangs out onthe forum, do join and introduce yourself & feel free to ask us questions!

For any security vulnerabilities or concerns, please contact us directly at security[at]speckle.systems.

Unless otherwise described, the code in this repository is licensed under the MIT License. Please note that some modules, extensions or code herein might be otherwise licensed. This is indicated either in the root of the containing folder under a different license file, or in the respective file's header. If you have any questions, don't hesitate to get in touch with us viaemail.