diff --git a/README.md b/README.md index 92dd016..fa2b32b 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,186 @@ -# xunit-Revit +# xUnitRevit [![Build Status](https://teocomi.visualstudio.com/Speckle/_apis/build/status/Speckle-Next.xunit-Revit?branchName=master)](https://teocomi.visualstudio.com/Speckle/_build/latest?definitionId=2&branchName=master) -xUnit runner for Revit +![image](https://user-images.githubusercontent.com/2679513/88956317-1acfaf80-d295-11ea-9741-58f2a196bdab.png) + + + +## Intro + +An xUnit runner for Autodesk Revit. Read more about this tool on our blog: TODO-LINK. + +xUnitRevit uses [speckle.xunit.runner.wpf](https://github.com/Speckle-Next/speckle.xunit.runner.wpf) which is a fork of [xunit.runner.wpf](https://github.com/Pilchie/xunit.runner.wpf), it allows to easily develop and run xUnit tests in Revit. + +Many thanks to all the developers of xunit.runner.wpf and xunit! + +### Structure + +This repo is composed of 2 projects: + +- xUnitRevit: the actual Revit addin +- xUnitRevitUtils: a utility library to help pass Revit data to the test libraries when running the tests + + + +## Getting Started + +There are very few steps required to create and run your fist unit tests with xUnitRevit: + +1. build/install xUnitRevit +2. create a test library +3. start Revit, launch the xUnitRevit addin and select the test library +4. done! Add a star ⭐ to our repo if it was useful 😉 + +### Building/installing xUnitRevit + +After cloning this repo, all you need to do to run xUnitRevit is to build the project in **Debug mode**, by selecting the build configuration that matches you Revit version. + +![image](https://user-images.githubusercontent.com/2679513/88941424-e5b96200-d280-11ea-8ef4-12fbb0ed13d2.png) + +**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 in **Release mode**, and manually copy the built files from `xunit-Revit\Release`. + +#### Configuration + +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 a `config_sample.json` in the root of the project, rename it `config.json` and set it to `copy 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 + +#### Dll locking + +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 to *edit & continue* your code while debugging, so you won't have to restart Revit each time. + +### Creating a test library + +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. + +#### Writing a simple test + +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 its `xru` static class. The code below shows how we can use it to get a list of Walls and check their properties. + +Full code : TODO_LINK + +```csharp + [Fact] +public void WallsHaveVolume() +{ + var testModel = GetTestModel("walls.rvt"); + var doc = xru.OpenDoc(testModel); + + var walls = new FilteredElementCollector(doc).WhereElementIsNotElementType().OfCategory(BuiltInCategory.OST_Walls).ToElements(); + + foreach(var wall in walls) + { + var volumeParam = wall.get_Parameter(BuiltInParameter.HOST_VOLUME_COMPUTED); + Assert.NotNull(volumeParam); + Assert.True(volumeParam.AsDouble() > 0); + } + doc.Close(false); +} +``` + +#### Writing tests with fixtures + +To be able to share context between tests, xUnits uses [fixtures](https://xunit.net/docs/shared-context). 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: LINK_TODO + +```csharp +public class DocFixture : IDisposable +{ + public Document Doc { get; set; } + public IList Walls { get; set; } + + + public DocFixture() + { + var testModel = Utils.GetTestModel("walls.rvt"); + Doc = xru.OpenDoc(testModel); + + Walls = new FilteredElementCollector(Doc).WhereElementIsNotElementType().OfCategory(BuiltInCategory.OST_Walls).ToElements(); + } + + public void Dispose() + { + } +} +public class TestWithFixture : IClassFixture +{ + DocFixture fixture; + public TestWithFixture(DocFixture fixture) + { + this.fixture = fixture; + } + + [Fact] + public void CountWalls() + { + Assert.Equal(4, fixture.Walls.Count); + } + + [Fact] + public void WallOffset() + { + var wall = fixture.Doc.GetElement(new ElementId(346573)); + var param = wall.get_Parameter(BuiltInParameter.WALL_BASE_OFFSET); + var baseOffset = UnitUtils.ConvertFromInternalUnits(param.AsDouble(), param.DisplayUnitType); + + Assert.Equal(2000, baseOffset); + } +} +``` + +#### Writing test that use Revit transactions + +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: + +```csharp +[Fact] +public void MoveWallsUp() +{ + var walls = fixture.Walls.Where(x => x.Id.IntegerValue != 346573); + + xru.RunInTransaction(() => + { + foreach(var wall in walls) + { + var param = wall.get_Parameter(BuiltInParameter.WALL_BASE_OFFSET); + var baseOffset = UnitUtils.ConvertToInternalUnits(2000, param.DisplayUnitType); + param.Set(baseOffset); + } + }, fixture.Doc) + .Wait(); // Important! Wait for action to finish + + foreach (var wall in walls) + { + var param = wall.get_Parameter(BuiltInParameter.WALL_BASE_OFFSET); + var baseOffset = UnitUtils.ConvertFromInternalUnits(param.AsDouble(), param.DisplayUnitType); + Assert.Equal(2000, baseOffset); + } +} +``` + +![image](https://user-images.githubusercontent.com/2679513/88953549-025d9600-d291-11ea-8ec4-58c85c84c5aa.png) + + + +## Final Notes + +xUnitRevit was developed to help us develop a better Speckle 2.0 connector for Revit, we hope you'll find it useful too. It's been currently tailored mostly for our needs, but please do give us feedback and submit PRs! + +### Contributing + +Want to suggest a feature, report a bug, submit a PR? Please open an issue to discuss first! + diff --git a/SampleLibrary/Properties/AssemblyInfo.cs b/SampleLibrary/Properties/AssemblyInfo.cs new file mode 100644 index 0000000..b756f97 --- /dev/null +++ b/SampleLibrary/Properties/AssemblyInfo.cs @@ -0,0 +1,36 @@ +using System.Reflection; +using System.Runtime.CompilerServices; +using System.Runtime.InteropServices; + +// General Information about an assembly is controlled through the following +// set of attributes. Change these attribute values to modify the information +// associated with an assembly. +[assembly: AssemblyTitle("SampleLibrary")] +[assembly: AssemblyDescription("")] +[assembly: AssemblyConfiguration("")] +[assembly: AssemblyCompany("")] +[assembly: AssemblyProduct("SampleLibrary")] +[assembly: AssemblyCopyright("Copyright © 2020")] +[assembly: AssemblyTrademark("")] +[assembly: AssemblyCulture("")] + +// Setting ComVisible to false makes the types in this assembly not visible +// to COM components. If you need to access a type in this assembly from +// COM, set the ComVisible attribute to true on that type. +[assembly: ComVisible(false)] + +// The following GUID is for the ID of the typelib if this project is exposed to COM +[assembly: Guid("c3a8684e-15bb-4b8b-b46c-35ace3729c35")] + +// Version information for an assembly consists of the following four values: +// +// Major Version +// Minor Version +// Build Number +// Revision +// +// You can specify all the values or you can default the Build and Revision Numbers +// by using the '*' as shown below: +// [assembly: AssemblyVersion("1.0.*")] +[assembly: AssemblyVersion("1.0.0.0")] +[assembly: AssemblyFileVersion("1.0.0.0")] diff --git a/SampleLibrary/SampleLibrary.csproj b/SampleLibrary/SampleLibrary.csproj new file mode 100644 index 0000000..bbd2dd6 --- /dev/null +++ b/SampleLibrary/SampleLibrary.csproj @@ -0,0 +1,92 @@ + + + + + + Debug + AnyCPU + {C3A8684E-15BB-4B8B-B46C-35ACE3729C35} + Library + Properties + SampleLibrary + SampleLibrary + v4.8 + 512 + true + + + + + + true + full + false + bin\Debug\ + DEBUG;TRACE + prompt + 4 + + + pdbonly + true + bin\Release\ + TRACE + prompt + 4 + + + + ..\packages\ModPlus.Revit.API.2021.1.0.0\lib\AdWindows.dll + + + ..\packages\ModPlus.Revit.API.2021.1.0.0\lib\RevitAPI.dll + + + ..\packages\ModPlus.Revit.API.2021.1.0.0\lib\RevitAPIUI.dll + + + + + + + + + + + ..\packages\xunit.abstractions.2.0.3\lib\net35\xunit.abstractions.dll + + + ..\packages\xunit.assert.2.4.1\lib\netstandard1.1\xunit.assert.dll + + + ..\packages\xunit.extensibility.core.2.4.1\lib\net452\xunit.core.dll + + + ..\packages\xunit.extensibility.execution.2.4.1\lib\net452\xunit.execution.desktop.dll + + + ..\packages\xUnitRevitUtils.2021.1.0.1\lib\netstandard2.0\xUnitRevitUtils.dll + + + + + + + + + + + + + + + + + + This project references NuGet package(s) that are missing on this computer. Use NuGet Package Restore to download them. For more information, see http://go.microsoft.com/fwlink/?LinkID=322105. The missing file is {0}. + + + + + + \ No newline at end of file diff --git a/SampleLibrary/SampleTest.cs b/SampleLibrary/SampleTest.cs new file mode 100644 index 0000000..af77ca1 --- /dev/null +++ b/SampleLibrary/SampleTest.cs @@ -0,0 +1,40 @@ +using Autodesk.Revit.DB; +using System; +using System.Collections.Generic; +using System.IO; +using Xunit; +using xUnitRevitUtils; + +namespace SampleLibrary +{ + public class SampleTest + { + /// + /// Checks wether all walls in the model have a valid volume + /// + [Fact] + public void WallsHaveVolume() + { + var testModel = Utils.GetTestModel("walls.rvt"); + var doc = xru.OpenDoc(testModel); + + var walls = new FilteredElementCollector(doc).WhereElementIsNotElementType().OfCategory(BuiltInCategory.OST_Walls).ToElements(); + + foreach(var wall in walls) + { + var volumeParam = wall.get_Parameter(BuiltInParameter.HOST_VOLUME_COMPUTED); + Assert.NotNull(volumeParam); + Assert.True(volumeParam.AsDouble() > 0); + } + } + + [Fact] + public void SampleFail() + { + var feet = UnitUtils.ConvertToInternalUnits(3000, DisplayUnitType.DUT_MILLIMETERS); + Assert.Equal(5, feet); + } + + + } +} diff --git a/SampleLibrary/TestModels/walls.rvt b/SampleLibrary/TestModels/walls.rvt new file mode 100644 index 0000000..4e6f35d Binary files /dev/null and b/SampleLibrary/TestModels/walls.rvt differ diff --git a/SampleLibrary/TestWithFixture.cs b/SampleLibrary/TestWithFixture.cs new file mode 100644 index 0000000..551a6f7 --- /dev/null +++ b/SampleLibrary/TestWithFixture.cs @@ -0,0 +1,79 @@ +using Autodesk.Revit.DB; +using System; +using System.Collections.Generic; +using System.IO; +using System.Linq; +using System.Text; +using System.Threading.Tasks; +using Xunit; +using xUnitRevitUtils; + +namespace SampleLibrary +{ + public class DocFixture : IDisposable + { + public Document Doc { get; set; } + public IList Walls { get; set; } + + + public DocFixture() + { + var testModel = Utils.GetTestModel("walls.rvt"); + Doc = xru.OpenDoc(testModel); + + Walls = new FilteredElementCollector(Doc).WhereElementIsNotElementType().OfCategory(BuiltInCategory.OST_Walls).ToElements(); + } + + public void Dispose() + { + } + } + public class TestWithFixture : IClassFixture + { + DocFixture fixture; + public TestWithFixture(DocFixture fixture) + { + this.fixture = fixture; + } + + [Fact] + public void CountWalls() + { + Assert.Equal(4, fixture.Walls.Count); + } + + [Fact] + public void WallOffset() + { + var wall = fixture.Doc.GetElement(new ElementId(346573)); + var param = wall.get_Parameter(BuiltInParameter.WALL_BASE_OFFSET); + var baseOffset = UnitUtils.ConvertFromInternalUnits(param.AsDouble(), param.DisplayUnitType); + + Assert.Equal(2000, baseOffset); + } + + [Fact] + public void MoveWallsUp() + { + var walls = fixture.Walls.Where(x => x.Id.IntegerValue != 346573); + + xru.RunInTransaction(() => + { + foreach(var wall in walls) + { + var param = wall.get_Parameter(BuiltInParameter.WALL_BASE_OFFSET); + var baseOffset = UnitUtils.ConvertToInternalUnits(2000, param.DisplayUnitType); + param.Set(baseOffset); + } + }, fixture.Doc) + .Wait(); // Important! Wait for action to finish + + foreach (var wall in walls) + { + var param = wall.get_Parameter(BuiltInParameter.WALL_BASE_OFFSET); + var baseOffset = UnitUtils.ConvertFromInternalUnits(param.AsDouble(), param.DisplayUnitType); + Assert.Equal(2000, baseOffset); + } + } + } +} diff --git a/SampleLibrary/Utils.cs b/SampleLibrary/Utils.cs new file mode 100644 index 0000000..4d94245 --- /dev/null +++ b/SampleLibrary/Utils.cs @@ -0,0 +1,24 @@ +using System; +using System.Collections.Generic; +using System.IO; +using System.Linq; +using System.Text; +using System.Threading.Tasks; + +namespace SampleLibrary +{ + public static class Utils + { + /// + /// Utility method to get models from local folder rather than an absolute path + /// + /// + /// + public static string GetTestModel(string filename) + { + var path = Path.Combine(Directory.GetCurrentDirectory(), "..", "..", "TestModels", filename); + return path; + + } + } +} diff --git a/SampleLibrary/packages.config b/SampleLibrary/packages.config new file mode 100644 index 0000000..8a38c3a --- /dev/null +++ b/SampleLibrary/packages.config @@ -0,0 +1,12 @@ + + + + + + + + + + + + \ No newline at end of file diff --git a/xUnitRevit.sln b/xUnitRevit.sln index 9d7b14a..9061394 100644 --- a/xUnitRevit.sln +++ b/xUnitRevit.sln @@ -11,8 +11,11 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "xUnitRevitUtils2020", "xUni EndProject Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "xUnitRevitUtils2019", "xUnitRevitUtils2019\xUnitRevitUtils2019.csproj", "{02399359-9CA0-4B47-B467-541E290E700F}" EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SampleLibrary", "SampleLibrary\SampleLibrary.csproj", "{C3A8684E-15BB-4B8B-B46C-35ACE3729C35}" +EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution + Debug|Any CPU = Debug|Any CPU Debug2019|Any CPU = Debug2019|Any CPU Debug2020|Any CPU = Debug2020|Any CPU Debug2021|Any CPU = Debug2021|Any CPU @@ -22,6 +25,8 @@ Global Release2021|Any CPU = Release2021|Any CPU EndGlobalSection GlobalSection(ProjectConfigurationPlatforms) = postSolution + {27A79ACA-7EA8-4406-8BB8-216578CC3AB7}.Debug|Any CPU.ActiveCfg = Debug2021|Any CPU + {27A79ACA-7EA8-4406-8BB8-216578CC3AB7}.Debug|Any CPU.Build.0 = Debug2021|Any CPU {27A79ACA-7EA8-4406-8BB8-216578CC3AB7}.Debug2019|Any CPU.ActiveCfg = Debug2019|Any CPU {27A79ACA-7EA8-4406-8BB8-216578CC3AB7}.Debug2019|Any CPU.Build.0 = Debug2019|Any CPU {27A79ACA-7EA8-4406-8BB8-216578CC3AB7}.Debug2020|Any CPU.ActiveCfg = Debug2020|Any CPU @@ -35,6 +40,8 @@ Global {27A79ACA-7EA8-4406-8BB8-216578CC3AB7}.Release2020|Any CPU.Build.0 = Release2020|Any CPU {27A79ACA-7EA8-4406-8BB8-216578CC3AB7}.Release2021|Any CPU.ActiveCfg = Release2021|Any CPU {27A79ACA-7EA8-4406-8BB8-216578CC3AB7}.Release2021|Any CPU.Build.0 = Release2021|Any CPU + {977E0B63-5706-4C2B-9C01-3C02D9EBE377}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {977E0B63-5706-4C2B-9C01-3C02D9EBE377}.Debug|Any CPU.Build.0 = Debug|Any CPU {977E0B63-5706-4C2B-9C01-3C02D9EBE377}.Debug2019|Any CPU.ActiveCfg = Debug|Any CPU {977E0B63-5706-4C2B-9C01-3C02D9EBE377}.Debug2020|Any CPU.ActiveCfg = Debug|Any CPU {977E0B63-5706-4C2B-9C01-3C02D9EBE377}.Debug2021|Any CPU.ActiveCfg = Debug|Any CPU @@ -45,6 +52,8 @@ Global {977E0B63-5706-4C2B-9C01-3C02D9EBE377}.Release2020|Any CPU.ActiveCfg = Release|Any CPU {977E0B63-5706-4C2B-9C01-3C02D9EBE377}.Release2021|Any CPU.ActiveCfg = Release|Any CPU {977E0B63-5706-4C2B-9C01-3C02D9EBE377}.Release2021|Any CPU.Build.0 = Release|Any CPU + {0DEF0F23-8AE2-461B-B014-8A0DA7494088}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {0DEF0F23-8AE2-461B-B014-8A0DA7494088}.Debug|Any CPU.Build.0 = Debug|Any CPU {0DEF0F23-8AE2-461B-B014-8A0DA7494088}.Debug2019|Any CPU.ActiveCfg = Debug|Any CPU {0DEF0F23-8AE2-461B-B014-8A0DA7494088}.Debug2020|Any CPU.ActiveCfg = Debug|Any CPU {0DEF0F23-8AE2-461B-B014-8A0DA7494088}.Debug2020|Any CPU.Build.0 = Debug|Any CPU @@ -55,6 +64,8 @@ Global {0DEF0F23-8AE2-461B-B014-8A0DA7494088}.Release2020|Any CPU.ActiveCfg = Release|Any CPU {0DEF0F23-8AE2-461B-B014-8A0DA7494088}.Release2020|Any CPU.Build.0 = Release|Any CPU {0DEF0F23-8AE2-461B-B014-8A0DA7494088}.Release2021|Any CPU.ActiveCfg = Release|Any CPU + {02399359-9CA0-4B47-B467-541E290E700F}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {02399359-9CA0-4B47-B467-541E290E700F}.Debug|Any CPU.Build.0 = Debug|Any CPU {02399359-9CA0-4B47-B467-541E290E700F}.Debug2019|Any CPU.ActiveCfg = Debug|Any CPU {02399359-9CA0-4B47-B467-541E290E700F}.Debug2019|Any CPU.Build.0 = Debug|Any CPU {02399359-9CA0-4B47-B467-541E290E700F}.Debug2020|Any CPU.ActiveCfg = Debug|Any CPU @@ -65,6 +76,22 @@ Global {02399359-9CA0-4B47-B467-541E290E700F}.Release2019|Any CPU.Build.0 = Release|Any CPU {02399359-9CA0-4B47-B467-541E290E700F}.Release2020|Any CPU.ActiveCfg = Release|Any CPU {02399359-9CA0-4B47-B467-541E290E700F}.Release2021|Any CPU.ActiveCfg = Release|Any CPU + {C3A8684E-15BB-4B8B-B46C-35ACE3729C35}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {C3A8684E-15BB-4B8B-B46C-35ACE3729C35}.Debug|Any CPU.Build.0 = Debug|Any CPU + {C3A8684E-15BB-4B8B-B46C-35ACE3729C35}.Debug2019|Any CPU.ActiveCfg = Debug|Any CPU + {C3A8684E-15BB-4B8B-B46C-35ACE3729C35}.Debug2019|Any CPU.Build.0 = Debug|Any CPU + {C3A8684E-15BB-4B8B-B46C-35ACE3729C35}.Debug2020|Any CPU.ActiveCfg = Debug|Any CPU + {C3A8684E-15BB-4B8B-B46C-35ACE3729C35}.Debug2020|Any CPU.Build.0 = Debug|Any CPU + {C3A8684E-15BB-4B8B-B46C-35ACE3729C35}.Debug2021|Any CPU.ActiveCfg = Debug|Any CPU + {C3A8684E-15BB-4B8B-B46C-35ACE3729C35}.Debug2021|Any CPU.Build.0 = Debug|Any CPU + {C3A8684E-15BB-4B8B-B46C-35ACE3729C35}.Release|Any CPU.ActiveCfg = Release|Any CPU + {C3A8684E-15BB-4B8B-B46C-35ACE3729C35}.Release|Any CPU.Build.0 = Release|Any CPU + {C3A8684E-15BB-4B8B-B46C-35ACE3729C35}.Release2019|Any CPU.ActiveCfg = Release|Any CPU + {C3A8684E-15BB-4B8B-B46C-35ACE3729C35}.Release2019|Any CPU.Build.0 = Release|Any CPU + {C3A8684E-15BB-4B8B-B46C-35ACE3729C35}.Release2020|Any CPU.ActiveCfg = Release|Any CPU + {C3A8684E-15BB-4B8B-B46C-35ACE3729C35}.Release2020|Any CPU.Build.0 = Release|Any CPU + {C3A8684E-15BB-4B8B-B46C-35ACE3729C35}.Release2021|Any CPU.ActiveCfg = Release|Any CPU + {C3A8684E-15BB-4B8B-B46C-35ACE3729C35}.Release2021|Any CPU.Build.0 = Release|Any CPU EndGlobalSection GlobalSection(SolutionProperties) = preSolution HideSolutionNode = FALSE diff --git a/xUnitRevit/xUnitRevit.csproj b/xUnitRevit/xUnitRevit.csproj index d29abdc..4fa2ee7 100644 --- a/xUnitRevit/xUnitRevit.csproj +++ b/xUnitRevit/xUnitRevit.csproj @@ -172,7 +172,7 @@ 5.4.1.1 - 1.0.5 + 1.0.8