Skip to content

Commit 44132b4

Browse files
ITaluoneITaluone
committed
Add new v7 upgrade guide
1 parent e6d15fb commit 44132b4

File tree

1 file changed

+2
-137
lines changed

1 file changed

+2
-137
lines changed

‎docs/_pages/upgradingtov7.md‎

Lines changed: 2 additions & 137 deletions
Original file line numberDiff line numberDiff line change
@@ -11,141 +11,6 @@ sidebar:
1111

1212
As of v7, we've decided to no longer directly target .NET Core. All versions of .NET Core, including .NET 5 are [already out of support by Microsoft](https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core). But we still support .NET Standard 2.0 and 2.1, so Fluent Assertions will still work with those deprecated frameworks.
1313

14-
## From `Execute.Assertion` to `AssertionChain`
14+
## Dropping support for `NSpec3` test framework
1515

16-
We've made quite some changes to the API that you use to build your own assertions. For example, the `BooleanAssertions` class was instantiated in `AssertionExtensions` like this:
17-
18-
```csharp
19-
public static BooleanAssertions Should(this bool actualValue)
20-
{
21-
return new BooleanAssertions(actualValue);
22-
}
23-
```
24-
25-
On turn, the `BooleanAssertions` would expose a `BeTrue` method
26-
27-
```csharp
28-
public AndConstraint<TAssertions> BeTrue(string because = "", params object[] becauseArgs)
29-
{
30-
Execute.Assertion
31-
.ForCondition(Subject == true)
32-
.BecauseOf(because, becauseArgs)
33-
.FailWith("Expected {context:boolean} to be {0}{reason}, but found {1}.", true, Subject);
34-
35-
return new AndConstraint<TAssertions>((TAssertions)this);
36-
}
37-
```
38-
39-
To be able to support chaining multiple assertions where the chained assertion can extend the caller identification, we introduced an `AssertionChain` class which instance can flow from one assertion to another. Because of that, the above code changed to:
40-
41-
```csharp
42-
public static BooleanAssertions Should(this bool actualValue)
43-
{
44-
return new BooleanAssertions(actualValue, AssertionChain.GetOrCreate());
45-
}
46-
```
47-
48-
Notice how we pass the call to `AssertionChain.GetOrCreate` to the assertions class? By default `GetOrCreate` will create a new instance of `AssertionChain`. But if the previous assertion method uses `AssertionChain.ReuseOnce`, `GetOrCreate` will return that reused instance only once.
49-
50-
The new `BeTrue` now looks like:
51-
52-
```csharp
53-
public AndConstraint<TAssertions> BeTrue(string because = "", params object[] becauseArgs)
54-
{
55-
assertionChain
56-
.ForCondition(Subject == true)
57-
.BecauseOf(because, becauseArgs)
58-
.FailWith("Expected {context:boolean} to be {0}{reason}, but found {1}.", true, Subject);
59-
60-
return new AndConstraint<TAssertions>((TAssertions)this);
61-
}
62-
```
63-
64-
So all of the methods to build an assertion that used to live on the `AssertionScope` (which is what `Execute.Assertion` returned), have now moved to `AssertionChain`. This is great because it allows the second assertion to get access to the state of the first assertion. For instance, if the first assertion failed, any successive attempts to call `FailWith` will not do anything.
65-
66-
## No more `ClearExpectation`
67-
68-
If you wanted to reuse the first part of the failure message across multiple failures, you could use the following construct (example taken from `TimeOnlyAssertions.BeCloseTo`):
69-
70-
```csharp
71-
Execute.Assertion
72-
.BecauseOf(because, becauseArgs)
73-
.WithExpectation("Expected {context:the time} to be within {0} from {1}{reason}, ", precision, nearbyTime)
74-
.ForCondition(Subject is not null)
75-
.FailWith("but found <null>.")
76-
.Then
77-
.ForCondition(Subject?.IsCloseTo(nearbyTime, precision) == true)
78-
.FailWith("but {0} was off by {1}.", Subject, difference)
79-
.Then
80-
.ClearExpectation();
81-
```
82-
83-
When using an `using new AssertionScope()` construct to wrap multiple assertions, all assertions executed within that scope will reuse the same instance of `AssertionScope` (which is what `Execute.Assertion` returned). The problem was that you had to explicitly call `ClearExpectation` to prevent the failure message passed to `WithExpectation` to leak into the next assertion within that scope. People often forgot that.
84-
85-
We solved this in v7, by making `WithExpectation` use a nested construct. This is what it now looks like:
86-
87-
```csharp
88-
assertionChain
89-
.BecauseOf(because, becauseArgs)
90-
.WithExpectation("Expected {context:the time} to be within {0} from {1}{reason}, ", precision, nearbyTime, chain => chain
91-
.ForCondition(Subject is not null)
92-
.FailWith("but found <null>.")
93-
.Then
94-
.ForCondition(Subject?.IsCloseTo(nearbyTime, precision) == true)
95-
.FailWith("but {0} was off by {1}.", Subject, difference)
96-
);
97-
```
98-
99-
All the code nested within the `WithExpectation` will share the first part of the failure message, and there's no need to explicitly clear it anymore.
100-
101-
## Amending caller identifiers with `WithPostfix`
102-
103-
Imagine the following chained assertion
104-
105-
```csharp
106-
var element = XElement.Parse(
107-
"""
108-
<parent>
109-
<child />
110-
<child />
111-
</parent>
112-
""");
113-
114-
115-
element.Should().HaveElement("child", AtLeast.Twice()).Which.Should().HaveCount(1);
116-
```
117-
118-
Prior to version 7, if the `HaveElement` assertion succeeded, but the `NotBeNull` failed, you would get the following exception:
119-
120-
Expected element to contain 1 item(s), but found 3: {<child />, <child />, <child />}.
121-
122-
Now, in v7, it'll will return the following:
123-
124-
Expected element/child to contain 1 item(s), but found 3: {<child />, <child />, <child />}.
125-
126-
This is possible because `HaveElement` will pass the `AssertionChain` through `ReuseOnce` to the succeeding `HaveCount()` _and_ amend the automatically detected caller identifier `element` (the part on which the first `Should` is invoked) with `"/child"` using `WithCallerPostfix`. Since this is a common thing in v7, the `AndWhichConstraint` has a constructor that does most of that automatically.
127-
128-
This is what `HaveElement` looks like (with some details left out):
129-
130-
```csharp
131-
public AndWhichConstraint<XElementAssertions, XElement> HaveElement(XName expected,
132-
string because = "", params object[] becauseArgs)
133-
{
134-
xElement = Subject!.Element(expected);
135-
136-
assertionChain
137-
.ForCondition(xElement is not null)
138-
.BecauseOf(because, becauseArgs)
139-
.FailWith(
140-
"Expected {context:subject} to have child element {0}{reason}, but no such child element was found.",
141-
expected.ToString().EscapePlaceholders());
142-
143-
return new AndWhichConstraint<XElementAssertions, XElement>(this, xElement, assertionChain, "/" + expected);
144-
}
145-
```
146-
147-
Notice the last argument to the `AndWhichConstraint` constructor.
148-
149-
## Other breaking changes
150-
151-
Check out the [release notes](releases.md) for other changes that might affect the upgrade to v7.
16+
In v7 we also decided to drop the support for the test framework `NSpec3` due to mor than 8 years of silence in the main repo.

0 commit comments

Comments
 (0)