As announced in December, we have published the pre-release version of SpecFlow v2. As hopefully the final version is also going to be released soon, it is good to be prepared how you can upgrade your existing projects to the new version.
Update: The final v2 has been released on January 27, 2016. Check out my summary of new features and the updated roadmap. I keep posting about features and details of v2. You can find these posts by filtering for the SpecFlow v2 tag.
NuGet or Visual Studio Gallery
First of all, it is important to highlight that the new release means a new package on NuGet only. The release cycle of the Visual Studio integration is different from the core product and from the next release on, the Visual Studio integration is going to use a different versioning scheme (e.g. v2016.1) in order to avoid confusions.
The Visual Studio integration is decoupled from the NuGet package (that contains the runtime and the generator) and generally a particular version of the Visual Studio integration supports a wider range of NuGet package versions. E.g. the current Visual Studio integration supports SpecFlow v1.8, v1.9 and also v2. This makes the upgrade process easier as you don’t have to upgrade all of your projects to SpecFlow v2 at once, the Visual Studio integration will work together with both the old and the new versions as well!
So don’t worry about the Visual Studio integration for now. (We will have a new release on that one too in a few months.)
When you should not upgrade
As described in the changelog, the new SpecFlow v2 targets .NET 4.5. This means if you have a project that is not upgraded yet, you should rather stay with the good old v1.9.
Upgrade SpecFlow step-by-step
Ok. So here are the necessary steps that work for sure.
1. Open your solution. Make sure it compiles, all tests passing, everything is committed.
2. Upgrade NuGet package. Select “References / Manage NuGet Packages…” from the context menu of the SpecFlow project node, and upgrade the SpecFlow package (by the time of writing this article you also have to enable “Include prerelease” as the final v2 has not been published yet).
An alternative to the previous step is to use the NuGet command prompt. This is definitely recommended if you have multiple SpecFlow projects. Select “Tools / NuGet Package Manager / Package Manager Console” from the Visual Studio menu and type:
PM> Update-Package SpecFlow -IncludePrerelease
3. Do not re-generate the feature files yet. If you see a popup asking for re-generating the feature files because of configuration changes, select “No”. The package upgrade reformats the app.config file and this is detected as a change. It is better to make sure that everything is fine before re-generating the files.
4. Open the app.config file and review the changes. It might be that you see only a duplicated comment about the documentation URL, but in some cases you will see duplicated settings. Fix these or simply undo the changes of this file.
So far, only the project file and the packages.config file have changed. Now we need to ensure that the feature files are properly re-generated.
Note: Since the generated code behind files are compatible, your project would compile already at this point and the tests would also run. However, in order to take the full advantage of SpecFlow v2, you should move on with re-generating the feature files.
5. Close and reopen the solution. Open a feature file in the reopened solution.
6. Re-generate feature files as suggested by the popup. If everything is fine, as you have opened the feature file, you will see a popup that there is a detected version change. Select “Yes”.
7. Wait until all feature files have been re-generated. This might take a while depending on the size of your project. But thanks to the new Gherkin3 parser, this should be much faster than it was before.
8. Verify feature code behind files. You can never be careful enough (or am I paranoid?), so it is good to know that everything worked well. If you open a code behind file, you should see something like this…
(Have you noticed? The code behind file does not contain the .NET runtime version anymore that caused fake changes if different team members were using different .NET updates. You will like v2!)
9. Build & Test. It should compile, and most probably your test will also pass. Just like before.
We are done! Hurray!
The first day with SpecFlow v2 for your colleagues
Well. There is one more thing to mention. I suppose you use NuGet package restore. This means you only changed the reference to the new SpecFlow version but your colleagues don’t have this new version yet. So in the unlikely case when they open their Visual Studio with the new codebase of your project and start modifying a feature file without restoring the NuGet packages first (ie. compile), their changes will be generated with the previous version of SpecFlow causing a slight inconsistency. The good news is that once they have restored the packages and saved the same file again, the new generator will be picked up.
—
You can learn and practice the new features of SpecFlow v2 on my SpecFlow course (official SpecFlow course). See the upcoming courses or book a private in-house course!