Skip to content

Commit a413ae9

Browse files
piotrzajacpiotrzajac
committed
Prepare documentation
1 parent da942a4 commit a413ae9

14 files changed

+389
-0
lines changed

‎docs/attributes/auto-mock-data-attribute.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# AutoMockData Attribute
2+
3+
Provides auto-generated data specimens generated by [AutoFixture](https://github.com/AutoFixture/AutoFixture) with a mocking library as an extension to xUnit.net's `Theory` attribute.
4+
5+
## Arguments
6+
7+
- `IgnoreVirtualMembers` - disables generation of members marked as `virtual`; by default set to `false`
8+
9+
## Example
10+
11+
```csharp
12+
[Theory]
13+
[AutoMockData]
14+
public void GivenCurrencyConverter_WhenConvertToPln_ThenMustReturnCorrectConvertedAmount(
15+
string testCurrencySymbol,
16+
[Frozen] ICurrencyExchangeProvider currencyProvider,
17+
CurrencyConverter currencyConverter)
18+
{
19+
// Arrange
20+
Mock.Get(currencyProvider)
21+
.Setup(cp => cp.GetCurrencyExchangeRate(testCurrencySymbol))
22+
.Returns(100M);
23+
24+
// Act
25+
decimal result = currencyConverter.ConvertToPln(testCurrencySymbol, 100M);
26+
27+
// Assert
28+
Assert.Equal(10000M, result);
29+
}
30+
```

‎docs/attributes/customize-with-attribute.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# CustomizeWith Attribute
2+
3+
An attribute that can be applied to parameters in an `AutoDataAttribute`-driven `Theory` to apply additional customization when the `IFixture` creates an instance of that type.
4+
5+
## Arguments
6+
7+
- `IncludeParameterType` - indicates whether attribute target parameter `Type` should be included as a first argument when creating customization; by default set to `false`
8+
9+
**Caution:** Order is important! Applying `CustomizeWith` attribute to the subsequent parameter makes preceding parameters of the same type to be created without specified customization and the particular parameter with the specified customization.
10+
11+
## Example
12+
13+
```csharp
14+
public class LocalDatesCustomization : ICustomization
15+
{
16+
public void Customize(IFixture fixture)
17+
{
18+
fixture.Register(() => LocalDate.FromDateTime(fixture.Create<DateTime>()));
19+
}
20+
}
21+
```
22+
23+
```csharp
24+
[Theory]
25+
[InlineAutoMockData("USD")]
26+
[InlineAutoMockData("EUR")]
27+
public void GivenCurrencyConverter_WhenConvertToPlnAtParticularDay_ThenMustReturnCorrectConvertedAmount(
28+
string testCurrencySymbol,
29+
[CustomizeWith(typeof(LocalDatesCustomization))] LocalDate day,
30+
[Frozen] ICurrencyExchangeProvider currencyProvider,
31+
CurrencyConverter currencyConverter)
32+
{
33+
// Arrange
34+
Mock.Get(currencyProvider)
35+
.Setup(cp => cp.GetCurrencyExchangeRate(testCurrencySymbol, day))
36+
.Returns(100M);
37+
38+
// Act
39+
decimal result = currencyConverter.ConvertToPln(testCurrencySymbol, 100M, day);
40+
41+
// Assert
42+
Assert.Equal(10000M, result);
43+
}
44+
```

‎docs/attributes/customize-with-t-attribute.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# CustomizeWith\<T> Attribute
2+
3+
A generic version of the `CustomizeWith` attribute has been introduced for ease of use. The same rules apply as for the non-generic version.
4+
5+
## Example
6+
7+
```csharp
8+
public class EmptyCollectionCustomization : ICustomization
9+
{
10+
public EmptyCollectionCustomization(Type reflectedType)
11+
{
12+
this.ReflectedType = reflectedType;
13+
}
14+
15+
public Type ReflectedType { get; }
16+
17+
public void Customize(IFixture fixture)
18+
{
19+
var emptyArray = Array.CreateInstance(this.ReflectedType.GenericTypeArguments.Single(), 0);
20+
21+
fixture.Customizations.Add(
22+
new FilteringSpecimenBuilder(
23+
new FixedBuilder(emptyArray),
24+
new ExactTypeSpecification(this.ReflectedType)));
25+
}
26+
}
27+
```
28+
29+
```csharp
30+
public sealed class EmptyCollectionAttribute : CustomizeWithAttribute<EmptyCollectionCustomization>
31+
{
32+
public EmptyCollectionAttribute()
33+
{
34+
this.IncludeParameterType = true;
35+
}
36+
}
37+
```
38+
39+
```csharp
40+
[Theory]
41+
[AutoData]
42+
public void CustomizeWithAttributeUsage(
43+
IList<string> firstStore,
44+
[EmptyCollection] IList<string> secondStore,
45+
IList<string> thirdStore,
46+
IList<int?> fourthStore)
47+
{
48+
Assert.NotEmpty(firstStore);
49+
Assert.Empty(secondStore);
50+
Assert.Empty(thirdStore);
51+
Assert.NotEmpty(fourthStore);
52+
}
53+
```

‎docs/attributes/except-attribute.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Except Attribute
2+
3+
Ensures that values from outside the specified list will be generated.
4+
5+
```csharp
6+
[Theory]
7+
[AutoData]
8+
public void ExceptAttributeUsage(
9+
[Except(DayOfWeek.Saturday, DayOfWeek.Sunday)] DayOfWeek workday)
10+
{
11+
Assert.True(workday is >= DayOfWeek.Monday and <= DayOfWeek.Friday);
12+
}
13+
```

‎docs/attributes/ignore-virtual-members-attribute.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# IgnoreVirtualMembers Attribute
2+
3+
An attribute that can be applied to parameters in an `AutoDataAttribute`-driven `Theory` to indicate that the parameter value should not have `virtual` properties populated when the `IFixture` creates an instance of that type.
4+
5+
This attribute allows to disable the generation of members marked as `virtual` on a decorated type whereas `IgnoreVirtualMembers` arguments of mocking attributes mentioned above disable such a generation for all types created by `IFixture`.
6+
7+
**Caution:** Order is important! Applying `IgnoreVirtualMembers` attribute to the subsequent parameter makes preceding parameters of the same type to have `virtual` properties populated and the particular parameter with the following ones of the same type to have `virtual` properties unpopulated.
8+
9+
## Example
10+
11+
```csharp
12+
public class User
13+
{
14+
public string Name { get; set; }
15+
public virtual Address Address { get; set; }
16+
}
17+
```
18+
19+
```csharp
20+
[Theory]
21+
[AutoData]
22+
public void IgnoreVirtualMembersUsage(
23+
User firstUser,
24+
[IgnoreVirtualMembers] User secondUser,
25+
User thirdUser)
26+
{
27+
Assert.NotNull(firstUser.Name);
28+
Assert.NotNull(firstUser.Address);
29+
30+
Assert.NotNull(secondUser.Name);
31+
Assert.Null(secondUser.Address);
32+
33+
Assert.NotNull(thirdUser.Name);
34+
Assert.Null(thirdUser.Address);
35+
}
36+
```

‎docs/attributes/index.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Attributes Overview
2+
3+
This section describes the main attributes provided by AutoFixture.XUnit2.AutoMock for use in your xUnit tests:
4+
5+
## Test Method Attributes
6+
7+
- [AutoMockData](auto-mock-data-attribute.md): Provides auto-generated data specimens using AutoFixture and a mocking library.
8+
- [InlineAutoMockData](inline-auto-mock-data-attribute.md): Combines inline values with auto-generated data specimens.
9+
- [MemberAutoMockData](member-auto-mock-data-attribute.md): Uses static members as data sources, combined with auto-generated data.
10+
- [IgnoreVirtualMembers](ignore-virtual-members-attribute.md): Disables generation of virtual members for a parameter or globally.
11+
- [CustomizeWith](customize-with-attribute.md): Applies additional customization to a parameter.
12+
- [CustomizeWith\<T>](customize-with-t-attribute.md): Generic version of CustomizeWith for ease of use.
13+
14+
## Data Filtering Attributes
15+
16+
- [Except](except-attribute.md): Ensures values from outside the specified list will be generated.
17+
- [PickFromRange](pick-from-range-attribute.md): Ensures only values from a specified range will be generated.
18+
- [PickNegative](pick-negative-attribute.md): Ensures only negative values will be generated.
19+
- [PickFromValues](pick-from-values-attribute.md): Ensures only values from the specified list will be generated.

‎docs/attributes/inline-auto-mock-data-attribute.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# InlineAutoMockData Attribute
2+
3+
Provides a data source for a `Theory`, with the data coming from inline values combined with auto-generated data specimens generated by [AutoFixture](https://github.com/AutoFixture/AutoFixture) with a mocking library.
4+
5+
## Arguments
6+
7+
- `IgnoreVirtualMembers` - disables generation of members marked as `virtual`; by default set to `false`
8+
9+
## Example
10+
11+
```csharp
12+
[Theory]
13+
[InlineAutoMockData("USD", 3, 10, 30)]
14+
[InlineAutoMockData("EUR", 4, 20, 80)]
15+
public void GivenCurrencyConverter_WhenConvertToPln_ThenMustReturnCorrectConvertedAmount(
16+
string testCurrencySymbol,
17+
decimal exchangeRate,
18+
decimal currencyAmount,
19+
decimal expectedPlnAmount,
20+
[Frozen] ICurrencyExchangeProvider currencyProvider,
21+
CurrencyConverter currencyConverter)
22+
{
23+
// Arrange
24+
Mock.Get(currencyProvider)
25+
.Setup(cp => cp.GetCurrencyExchangeRate(testCurrencySymbol))
26+
.Returns(exchangeRate);
27+
28+
// Act
29+
decimal result = currencyConverter.ConvertToPln(testCurrencySymbol, currencyAmount);
30+
31+
// Assert
32+
Assert.Equal(expectedPlnAmount, result);
33+
}
34+
```

‎docs/attributes/member-auto-mock-data-attribute.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# MemberAutoMockData Attribute
2+
3+
Provides a data source for a `Theory`, with the data coming from one of the following sources:
4+
5+
- A static property
6+
- A static field
7+
- A static method (with parameters)
8+
9+
combined with auto-generated data specimens generated by [AutoFixture](https://github.com/AutoFixture/AutoFixture) with a mocking library.
10+
11+
The member must return something compatible with `Enumerable<object[]>` with the test data.
12+
13+
**Caution:** The property is completely enumerated by .ToList() before any test is run. Hence it should return independent object sets.
14+
15+
## Arguments
16+
17+
- `IgnoreVirtualMembers` - disables generation of members marked as `virtual`; by default set to `false`
18+
- `ShareFixture` - indicates whether to share a `fixture` across all data items should be used or new one; by default set to `true`
19+
20+
## Example
21+
22+
```csharp
23+
public class CurrencyConverterFixture
24+
{
25+
public static IEnumerable<object[]> CurrencyConversionRatesWithResult()
26+
{
27+
return new List<object[]>
28+
{
29+
new object[] { "USD", 3M, 10M, 30M },
30+
new object[] { "EUR", 4M, 20M, 80M }
31+
};
32+
}
33+
}
34+
```
35+
36+
```csharp
37+
[Theory]
38+
[MemberAutoMockData("CurrencyConversionRatesWithResult", MemberType = typeof(CurrencyConverterFixture))]
39+
public void GivenCurrencyConverter_WhenConvertToPln_ThenMustReturnCorrectConvertedAmount(
40+
string testCurrencySymbol,
41+
decimal exchangeRate,
42+
decimal currencyAmount,
43+
decimal expectedPlnAmount,
44+
[Frozen] ICurrencyExchangeProvider currencyProvider,
45+
CurrencyConverter currencyConverter)
46+
{
47+
// Arrange
48+
Mock.Get(currencyProvider)
49+
.Setup(cp => cp.GetCurrencyExchangeRate(testCurrencySymbol))
50+
.Returns(exchangeRate);
51+
52+
// Act
53+
decimal result = currencyConverter.ConvertToPln(testCurrencySymbol, currencyAmount);
54+
55+
// Assert
56+
Assert.Equal(expectedPlnAmount, result);
57+
}
58+
```

‎docs/attributes/pick-from-range-attribute.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# PickFromRange Attribute
2+
3+
Ensures that only values from a specified range will be generated.
4+
5+
```csharp
6+
[Theory]
7+
[AutoData]
8+
public void RangeAttributeUsage(
9+
[PickFromRange(11, 19)] int teenagerAge)
10+
{
11+
Assert.True(teenagerAge is > 11 and < 19);
12+
}
13+
```

‎docs/attributes/pick-from-values-attribute.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# PickFromValues Attribute
2+
3+
Ensures that only values from the specified list will be generated.
4+
5+
```csharp
6+
[Theory]
7+
[AutoData]
8+
public void ValuesAttributeUsage(
9+
[PickFromValues(DayOfWeek.Saturday, DayOfWeek.Sunday)] HashSet<DayOfWeek> weekend)
10+
{
11+
var weekendDays = new[] { DayOfWeek.Saturday, DayOfWeek.Sunday };
12+
Assert.Equivalent(weekendDays, weekend);
13+
}
14+
```

0 commit comments

Comments
 (0)