Prepare documentation

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

@@ -0,0 +1,30 @@
+# AutoMockData Attribute
+
+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.
+
+## Arguments
+
+- `IgnoreVirtualMembers` - disables generation of members marked as `virtual`; by default set to `false`
+
+## Example
+
+```csharp
+[Theory]
+[AutoMockData]
+public void GivenCurrencyConverter_WhenConvertToPln_ThenMustReturnCorrectConvertedAmount(
+    string testCurrencySymbol,
+    [Frozen] ICurrencyExchangeProvider currencyProvider,
+    CurrencyConverter currencyConverter)
+{
+    // Arrange
+    Mock.Get(currencyProvider)
+        .Setup(cp => cp.GetCurrencyExchangeRate(testCurrencySymbol))
+        .Returns(100M);
+
+    // Act
+    decimal result = currencyConverter.ConvertToPln(testCurrencySymbol, 100M);
+
+    // Assert
+    Assert.Equal(10000M, result);
+}
+```

docs/attributes/customize-with-attribute.md

@@ -0,0 +1,44 @@
+# CustomizeWith Attribute
+
+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.
+
+## Arguments
+
+- `IncludeParameterType` - indicates whether attribute target parameter `Type` should be included as a first argument when creating customization; by default set to `false`
+
+**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.
+
+## Example
+
+```csharp
+public class LocalDatesCustomization : ICustomization
+{
+    public void Customize(IFixture fixture)
+    {
+        fixture.Register(() => LocalDate.FromDateTime(fixture.Create<DateTime>()));
+    }
+}
+```
+
+```csharp
+[Theory]
+[InlineAutoMockData("USD")]
+[InlineAutoMockData("EUR")]
+public void GivenCurrencyConverter_WhenConvertToPlnAtParticularDay_ThenMustReturnCorrectConvertedAmount(
+    string testCurrencySymbol,
+    [CustomizeWith(typeof(LocalDatesCustomization))] LocalDate day,
+    [Frozen] ICurrencyExchangeProvider currencyProvider,
+    CurrencyConverter currencyConverter)
+{
+    // Arrange
+    Mock.Get(currencyProvider)
+        .Setup(cp => cp.GetCurrencyExchangeRate(testCurrencySymbol, day))
+        .Returns(100M);
+
+    // Act
+    decimal result = currencyConverter.ConvertToPln(testCurrencySymbol, 100M, day);
+
+    // Assert
+    Assert.Equal(10000M, result);
+}
+```

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

@@ -0,0 +1,53 @@
+# CustomizeWith\<T> Attribute
+
+A generic version of the `CustomizeWith` attribute has been introduced for ease of use. The same rules apply as for the non-generic version.
+
+## Example
+
+```csharp
+public class EmptyCollectionCustomization : ICustomization
+{
+    public EmptyCollectionCustomization(Type reflectedType)
+    {
+        this.ReflectedType = reflectedType;
+    }
+
+    public Type ReflectedType { get; }
+
+    public void Customize(IFixture fixture)
+    {
+        var emptyArray = Array.CreateInstance(this.ReflectedType.GenericTypeArguments.Single(), 0);
+
+        fixture.Customizations.Add(
+            new FilteringSpecimenBuilder(
+                new FixedBuilder(emptyArray),
+                new ExactTypeSpecification(this.ReflectedType)));
+    }
+}
+```
+
+```csharp
+public sealed class EmptyCollectionAttribute : CustomizeWithAttribute<EmptyCollectionCustomization>
+{
+    public EmptyCollectionAttribute()
+    {
+        this.IncludeParameterType = true;
+    }
+}
+```
+
+```csharp
+[Theory]
+[AutoData]
+public void CustomizeWithAttributeUsage(
+    IList<string> firstStore,
+    [EmptyCollection] IList<string> secondStore,
+    IList<string> thirdStore,
+    IList<int?> fourthStore)
+{
+    Assert.NotEmpty(firstStore);
+    Assert.Empty(secondStore);
+    Assert.Empty(thirdStore);
+    Assert.NotEmpty(fourthStore);
+}
+```

docs/attributes/except-attribute.md

@@ -0,0 +1,13 @@
+# Except Attribute
+
+Ensures that values from outside the specified list will be generated.
+
+```csharp
+[Theory]
+[AutoData]
+public void ExceptAttributeUsage(
+    [Except(DayOfWeek.Saturday, DayOfWeek.Sunday)] DayOfWeek workday)
+{
+    Assert.True(workday is >= DayOfWeek.Monday and <= DayOfWeek.Friday);
+}
+```

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

@@ -0,0 +1,36 @@
+# IgnoreVirtualMembers Attribute
+
+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.
+
+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`.
+
+**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.
+
+## Example
+
+```csharp
+public class User
+{
+    public string Name { get; set; }
+    public virtual Address Address { get; set; }
+}
+```
+
+```csharp
+[Theory]
+[AutoData]
+public void IgnoreVirtualMembersUsage(
+    User firstUser,
+    [IgnoreVirtualMembers] User secondUser,
+    User thirdUser)
+{
+    Assert.NotNull(firstUser.Name);
+    Assert.NotNull(firstUser.Address);
+
+    Assert.NotNull(secondUser.Name);
+    Assert.Null(secondUser.Address);
+
+    Assert.NotNull(thirdUser.Name);
+    Assert.Null(thirdUser.Address);
+}
+```

docs/attributes/index.md

@@ -0,0 +1,19 @@
+# Attributes Overview
+
+This section describes the main attributes provided by AutoFixture.XUnit2.AutoMock for use in your xUnit tests:
+
+## Test Method Attributes
+
+- [AutoMockData](auto-mock-data-attribute.md): Provides auto-generated data specimens using AutoFixture and a mocking library.
+- [InlineAutoMockData](inline-auto-mock-data-attribute.md): Combines inline values with auto-generated data specimens.
+- [MemberAutoMockData](member-auto-mock-data-attribute.md): Uses static members as data sources, combined with auto-generated data.
+- [IgnoreVirtualMembers](ignore-virtual-members-attribute.md): Disables generation of virtual members for a parameter or globally.
+- [CustomizeWith](customize-with-attribute.md): Applies additional customization to a parameter.
+- [CustomizeWith\<T>](customize-with-t-attribute.md): Generic version of CustomizeWith for ease of use.
+
+## Data Filtering Attributes
+
+- [Except](except-attribute.md): Ensures values from outside the specified list will be generated.
+- [PickFromRange](pick-from-range-attribute.md): Ensures only values from a specified range will be generated.
+- [PickNegative](pick-negative-attribute.md): Ensures only negative values will be generated.
+- [PickFromValues](pick-from-values-attribute.md): Ensures only values from the specified list will be generated.

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

@@ -0,0 +1,34 @@
+# InlineAutoMockData Attribute
+
+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.
+
+## Arguments
+
+- `IgnoreVirtualMembers` - disables generation of members marked as `virtual`; by default set to `false`
+
+## Example
+
+```csharp
+[Theory]
+[InlineAutoMockData("USD", 3, 10, 30)]
+[InlineAutoMockData("EUR", 4, 20, 80)]
+public void GivenCurrencyConverter_WhenConvertToPln_ThenMustReturnCorrectConvertedAmount(
+    string testCurrencySymbol,
+    decimal exchangeRate,
+    decimal currencyAmount,
+    decimal expectedPlnAmount,
+    [Frozen] ICurrencyExchangeProvider currencyProvider,
+    CurrencyConverter currencyConverter)
+{
+    // Arrange
+    Mock.Get(currencyProvider)
+        .Setup(cp => cp.GetCurrencyExchangeRate(testCurrencySymbol))
+        .Returns(exchangeRate);
+
+    // Act
+    decimal result = currencyConverter.ConvertToPln(testCurrencySymbol, currencyAmount);
+
+    // Assert
+    Assert.Equal(expectedPlnAmount, result);
+}
+```

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

@@ -0,0 +1,58 @@
+# MemberAutoMockData Attribute
+
+Provides a data source for a `Theory`, with the data coming from one of the following sources:
+
+- A static property
+- A static field
+- A static method (with parameters)
+
+combined with auto-generated data specimens generated by [AutoFixture](https://github.com/AutoFixture/AutoFixture) with a mocking library.
+
+The member must return something compatible with `Enumerable<object[]>` with the test data.
+
+**Caution:** The property is completely enumerated by .ToList() before any test is run. Hence it should return independent object sets.
+
+## Arguments
+
+- `IgnoreVirtualMembers` - disables generation of members marked as `virtual`; by default set to `false`
+- `ShareFixture` - indicates whether to share a `fixture` across all data items should be used or new one; by default set to `true`
+
+## Example
+
+```csharp
+public class CurrencyConverterFixture
+{
+    public static IEnumerable<object[]> CurrencyConversionRatesWithResult()
+    {
+        return new List<object[]>
+            {
+                new object[] { "USD", 3M, 10M, 30M },
+                new object[] { "EUR", 4M, 20M, 80M }
+            };
+    }
+}
+```
+
+```csharp
+[Theory]
+[MemberAutoMockData("CurrencyConversionRatesWithResult", MemberType = typeof(CurrencyConverterFixture))]
+public void GivenCurrencyConverter_WhenConvertToPln_ThenMustReturnCorrectConvertedAmount(
+    string testCurrencySymbol,
+    decimal exchangeRate,
+    decimal currencyAmount,
+    decimal expectedPlnAmount,
+    [Frozen] ICurrencyExchangeProvider currencyProvider,
+    CurrencyConverter currencyConverter)
+{
+    // Arrange
+    Mock.Get(currencyProvider)
+        .Setup(cp => cp.GetCurrencyExchangeRate(testCurrencySymbol))
+        .Returns(exchangeRate);
+
+    // Act
+    decimal result = currencyConverter.ConvertToPln(testCurrencySymbol, currencyAmount);
+
+    // Assert
+    Assert.Equal(expectedPlnAmount, result);
+}
+```

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

@@ -0,0 +1,13 @@
+# PickFromRange Attribute
+
+Ensures that only values from a specified range will be generated.
+
+```csharp
+[Theory]
+[AutoData]
+public void RangeAttributeUsage(
+    [PickFromRange(11, 19)] int teenagerAge)
+{
+    Assert.True(teenagerAge is > 11 and < 19);
+}
+```

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

@@ -0,0 +1,14 @@
+# PickFromValues Attribute
+
+Ensures that only values from the specified list will be generated.
+
+```csharp
+[Theory]
+[AutoData]
+public void ValuesAttributeUsage(
+    [PickFromValues(DayOfWeek.Saturday, DayOfWeek.Sunday)] HashSet<DayOfWeek> weekend)
+{
+    var weekendDays = new[] { DayOfWeek.Saturday, DayOfWeek.Sunday };
+    Assert.Equivalent(weekendDays, weekend);
+}
+```

docs/attributes/pick-negative-attribute.md

@@ -0,0 +1,15 @@
+# PickNegative Attribute
+
+Ensures that only negative values will be generated.
+
+**Caution:** It will throw an exception when being used on an unsupported type or on one which does not accept negative values.
+
+```csharp
+[Theory]
+[AutoData]
+public void NegativeAttributeUsage(
+    [PickNegative] int negativeNumber)
+{
+    Assert.True(negativeNumber < 0);
+}
+```

docs/index.md

@@ -0,0 +1,9 @@
+# About AutoFixture.XUnit2.AutoMock
+
+AutoFixture.XUnit2.AutoMock is a free, open source tool which accelerates preparation of mocked structures for unit tests under [XUnit2](http://xunit.github.io/) by configuring [AutoFixture](https://github.com/AutoFixture/AutoFixture) data generation to use a mocking library of your choice. Gracefully handles recursive structures by omitting recursions.
+
+## Table of Contents
+
+- [Supported Mocking Libraries](supported-mocking-libraries.md)
+- [Attributes](attributes/index.md)
+- [Tips and Tricks](tips-and-tricks.md)

docs/supported-mocking-libraries.md

@@ -0,0 +1,7 @@
+# Supported Mocking Libraries
+
+| Mocking library                                           | Corresponding NuGet package |
+| ---------------------------------------------------------:|:--------------------------- |
+| [Moq](https://github.com/moq/moq4)                        | [![AutoMoq](https://img.shields.io/nuget/v/Objectivity.AutoFixture.XUnit2.AutoMoq.svg?logo=nuget&style=flat-square&label=AutoMoq)![Downloads](https://img.shields.io/nuget/dt/Objectivity.AutoFixture.XUnit2.AutoMoq.svg?style=flat-square&label)](https://www.nuget.org/packages/Objectivity.AutoFixture.XUnit2.AutoMoq/) |
+| [NSubstitute](https://github.com/nsubstitute/NSubstitute) | [![AutoNSubstitute](https://img.shields.io/nuget/v/Objectivity.AutoFixture.XUnit2.AutoNSubstitute.svg?logo=nuget&style=flat-square&label=AutoNSubstitute)![Downloads](https://img.shields.io/nuget/dt/Objectivity.AutoFixture.XUnit2.AutoNSubstitute.svg?style=flat-square&label)](https://www.nuget.org/packages/Objectivity.AutoFixture.XUnit2.AutoNSubstitute/) |
+| [FakeItEasy](https://github.com/FakeItEasy/FakeItEasy)    | [![AutoFakeItEasy](https://img.shields.io/nuget/v/Objectivity.AutoFixture.XUnit2.AutoFakeItEasy.svg?logo=nuget&style=flat-square&label=AutoFakeItEasy)![Downloads](https://img.shields.io/nuget/dt/Objectivity.AutoFixture.XUnit2.AutoFakeItEasy.svg?style=flat-square&label)](https://www.nuget.org/packages/Objectivity.AutoFixture.XUnit2.AutoFakeItEasy) |