feat: Add bind function to simulate @Bind directive (#750)

* feat: Add bind function to simulate @Bind directive

* add: Documentation and samples

* added null checks and tests

* Apply suggestions from code review

Co-authored-by: Egil Hansen <egil@assimilated.dk>

* Better explanation if Bind encounters an error

* Added Tests

* tweaks to error messages

* Only replace last instance instead of every

* Apply suggestions from code review

Co-authored-by: Egil Hansen <egil@assimilated.dk>

* added e2e test

* wip - compare bind with Bind

* Added small example for bind in CHANGELOG.md

* improved bind compare test

* Update CHANGELOG.md

* fix changelog

Co-authored-by: Egil Hansen <egil@assimilated.dk>

Author: linkdotnet

CHANGELOG.md

@@ -6,6 +6,34 @@ All notable changes to **bUnit** will be documented in this file. The project ad
 
 ## [Unreleased]
 
+### Added
+
+- Added `Bind` method to parameter builder that makes it easier to emulate the `@bind-Value` syntax in C#-based tests. 
+  
+  When writing tests in razor files, the `@bind-` directive can be directly applied like this: 
+	
+  ```razor
+  <MyComponent @bind-Value="myParam"></MyComponent>
+  ```
+	
+  The same expression in C# syntax is more verbose like this:  
+ 
+  ```csharp
+  RenderComponent<MyComponent>(ps => ps
+    .Add(c => c.Value, value)
+    .Add(c => c.ValueChanged, newValue => value = newValue)
+    .Add(c => c.ValueExpression, () => value));
+  ```
+    
+  With the new `Bind` method this can be done in one method:
+    
+  ```csharp
+  RenderComponent<MyComponent>(ps => ps
+    .Bind(c => c.Value, value, newValue => value = newValue, () => value));
+  ```
+  
+  By [@linkdotnet](https://github.com/linkdotnet) and [@egil](https://github.com/egil).
+
 ## [1.9.8] - 2022-06-07
 
 ### Changed

docs/samples/components/TwoWayBinding.razor

@@ -0,0 +1,4 @@
+@code {
+  [Parameter] public string Value { get; set; } = string.Empty;
+  [Parameter] public EventCallback<string> ValueChanged { get; set; }
+}

docs/samples/tests/razor/TwoWayBindingTest.razor

@@ -0,0 +1,10 @@
+@code {
+  [Fact]
+  public void Test()
+  {
+    using var ctx = new TestContext();
+    var currentValue = string.Empty;
+
+    var cut = ctx.Render(@<TwoWayBinding @bind-Value="currentValue"></TwoWayBinding>);
+  }
+}

docs/samples/tests/xunit/TwoWayBindingTest.cs

@@ -0,0 +1,19 @@
+using Xunit;
+
+namespace Bunit.Docs.Samples;
+
+public class TwoWayBindingTest
+{
+  [Fact]
+  public void Test()
+  {
+    using var ctx = new TestContext();
+    var currentValue = string.Empty;
+
+    ctx.RenderComponent<TwoWayBinding>(parameters =>
+      parameters.Bind(
+        p => p.Value,
+        currentValue,
+        newValue => currentValue = newValue));
+  }
+}

docs/site/docs/providing-input/passing-parameters-to-components.md

@@ -375,18 +375,37 @@ It is possible to nest a component under tests inside other components, if that
 
 # [C# test code](#tab/csharp)
 
-[!code-csharp[](../../../samples/tests/xunit/NestedComponentTest.cs#L11-L23)]
+[!code-csharp[NestedComponentTest](../../../samples/tests/xunit/NestedComponentTest.cs#L11-L23)]
 
 The example renders the `<HelloWorld>` component inside the `<Wrapper>` component. What is special in both cases is the use of the `FindComponent<HelloWorld>()` that returns a `IRenderedComponent<HelloWorld>`. This is needed because the `RenderComponent<Wrapper>` method call returns an `IRenderedComponent<Wrapper>` instance, that provides access to the instance of the `<Wrapper>` component, but not the `<HelloWorld>`-component instance.
 
 # [Razor test code](#tab/razor)
 
-[!code-cshtml[](../../../samples/tests/razor/NestedComponentTest.razor)]
+[!code-cshtml[NestedComponentTest](../../../samples/tests/razor/NestedComponentTest.razor)]
 
 The example passes a inline Razor template to the `Render<TComponent>()` method. What is different here from the previous examples is that we use the generic version of the `Render<TComponent>` method, which is a shorthand for `Render(...).FindComponent<TComponent>()`.
 
 ***
 
+## Configure two-way with component parameters (`@bind` directive)
+
+To set up [two-way binding to a pair of component parameters](https://docs.microsoft.com/en-us/aspnet/core/blazor/components/data-binding#binding-with-component-parameters) on a component under test, e.g. the `Value` and `ValueChanged` parameter pair on the component below, do the following:
+
+[!code-csharp[TwoWayBinding.razor](../../../samples/components/TwoWayBinding.razor)]
+
+# [C# test code](#tab/csharp)
+
+[!code-csharp[TwoWayBindingTest.cs](../../../samples/tests/xunit/TwoWayBindingTest.cs#L5-L19)]
+
+The example uses the `Bind` method to setup two-way binding between the `Value` parameter and `ValueChanged` parameter, and the local variable in the test method (`currentValue`). The `Bind` method is a shorthand for calling the the `Add` method for the `Value` parameter and `ValueChanged` parameter individually.
+
+# [Razor test code](#tab/razor)
+
+[!code-cshtml[TwoWayBindingTest.razor](../../../samples/tests/razor/TwoWayBindingTest.razor)]
+
+The example uses the standard `@bind-Value` directive in Blazor to set up two way binding between the `Value` parameter and `ValueChanged` parameter and the local variable in the test method (`currentValue`).
+***
+
 ## Further Reading
 
 - <xref:inject-services>

src/bunit.core/ComponentParameterCollectionBuilder.cs

@@ -314,6 +314,79 @@ public ComponentParameterCollectionBuilder<TComponent> AddUnmatched(string name,
 		return AddParameter(name, value);
 	}
 
+	/// <summary>Adds two-way binding, simulating the <c>@bind-Parameter</c> directive, to a given pair of parameters.</summary>
+	/// <param name="parameterSelector">Parameter-selector for the two-way binding.</param>
+	/// <param name="initialValue">The initial value to pass to <typeparamref name="TComponent"/>.</param>
+	/// <param name="changedAction">Action which gets invoked when the value has changed.</param>
+	/// <param name="valueExpression">Optional value expression.</param>
+	/// <returns>This <see cref="ComponentParameterCollectionBuilder{TComponent}"/>.</returns>
+	/// <remarks>
+	/// This function is a short-hand form for the following expression:
+	/// <code>RenderComponent&lt;<typeparamref name="TComponent"/>&gt;(ps => ps
+	///   .Add(c => c.Value, value)
+	///   .Add(c => c.ValueChanged, newValue => value = newValue)
+	///   .Add(c => c.ValueExpression, () => value));
+	/// </code>
+	/// With <c>Bind</c>, it can be written like this:
+	/// <code>RenderComponent&lt;<typeparamref name="TComponent"/>&gt;(ps => ps
+	///   .Bind(c => c.Value, value, newValue => value = newValue, () => value));
+	/// </code>
+	/// </remarks>
+	public ComponentParameterCollectionBuilder<TComponent> Bind<TValue>(
+		Expression<Func<TComponent, TValue>> parameterSelector,
+		TValue initialValue,
+		Action<TValue> changedAction,
+		Expression<Func<TValue>>? valueExpression = null)
+	{
+		var (parameterName, _, isCascading) = GetParameterInfo(parameterSelector);
+
+		if (isCascading)
+			throw new ArgumentException("Using Bind with a cascading parameter is not allowed.", parameterName);
+		
+		if (changedAction is null)
+        	throw new ArgumentNullException(nameof(changedAction));
+
+		var changedName = $"{parameterName}Changed";
+		var expressionName = $"{parameterName}Expression";
+
+		AssertBindTargetIsCorrect(parameterName, parameterSelector);
+
+		if (!HasPublicParameterProperty(changedName))
+			throw new InvalidOperationException($"The parameter selector '{parameterSelector}' does not resolve to a " +
+												$"parameter that has a related parameter with the name {changedName}. " +
+												$"This is required for two way binding.");
+
+		AddParameter(parameterName, initialValue);
+		AddParameter(changedName, EventCallback.Factory.Create(changedAction.Target!, changedAction));
+
+		return !HasPublicParameterProperty(expressionName)
+			? this 
+			: AddParameter(expressionName, valueExpression ?? (() => initialValue));
+
+		static void AssertBindTargetIsCorrect(string parameterName, Expression<Func<TComponent, TValue>> parameterSelector)
+		{
+			var isBindEventParameter = parameterName.EndsWith("Changed", StringComparison.Ordinal) || parameterName.EndsWith("Expression", StringComparison.Ordinal);
+			var isBindEventType = IsConcreteGenericOf(typeof(TValue), typeof(EventCallback<>)) || IsConcreteGenericOf(typeof(TValue), typeof(Expression<>));
+			if (isBindEventParameter && isBindEventType)
+			{
+				var selectorExpression = parameterSelector.ToString();
+				var possibleSelector = TrimEnd(parameterName, "Changed");
+				possibleSelector = TrimEnd(possibleSelector, "Expression");
+				throw new ArgumentException($"The parameter selector {selectorExpression} does not correspond " +
+											$"to a valid target for a @bind expression.{Environment.NewLine}If the structure of the " +
+											$"component is <MyComponent @bind-Value=\"value\" /> call " +
+											$"Bind(p => p.Value, \"initial value\", p => p.ValueChanged, v => someVar = v);" +
+											Environment.NewLine +
+											$"Try {selectorExpression.Replace(parameterName, possibleSelector, StringComparison.Ordinal)} instead.");
+			}
+		}
+		
+		static string TrimEnd(string source, string value) 
+			=> source.EndsWith(value, StringComparison.Ordinal)
+			? source.Remove(source.LastIndexOf(value, StringComparison.Ordinal))
+			: source;
+	}
+
 	/// <summary>
 	/// Try to add a <paramref name="value"/> for a parameter with the <paramref name="name"/>, if
 	/// <typeparamref name="TComponent"/> has a property with that name, AND that property has a <see cref="ParameterAttribute"/>
@@ -401,4 +474,20 @@ private static RenderFragment GetRenderFragment<TChildComponent>(Action<Componen
 		var childBuilder = new ComponentParameterCollectionBuilder<TChildComponent>(childParameterBuilder);
 		return childBuilder.Build().ToRenderFragment<TChildComponent>();
 	}
-}
+	
+	private static bool HasPublicParameterProperty(string parameterName)
+	{
+		var type = typeof(TComponent);
+		var property = type.GetProperty(parameterName);
+
+		return property != null && property.GetCustomAttributes(inherit: true).Any(a => a is ParameterAttribute);
+	}
+	
+	private static bool IsConcreteGenericOf(Type type, Type openGeneric)
+	{
+		if (!type.IsGenericType)
+			return false;
+
+		return type.GetGenericTypeDefinition() == openGeneric;
+	}
+}