/* ========================================================================
* Copyright (c) 2005-2025 The OPC Foundation, Inc. All rights reserved.
*
* OPC Foundation MIT License 1.00
*
* Permission is hereby granted, free of charge, to any person
* obtaining a copy of this software and associated documentation
* files (the "Software"), to deal in the Software without
* restriction, including without limitation the rights to use,
* copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the
* Software is furnished to do so, subject to the following
* conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
* WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
* OTHER DEALINGS IN THE SOFTWARE.
*
* The complete license agreement can be found here:
* http://opcfoundation.org/License/MIT/1.00/
* ======================================================================*/
// CA2000: test code; many disposables are ownership-transferred to test fixtures or short-lived,
// making CA2000 noisy without a real leak risk. Disabled file-level for the suite.
#pragma warning disable CA2000
using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Diagnostics.Metrics;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;
using Moq;
using NUnit.Framework;
using Opc.Ua.Tests;
namespace Opc.Ua.Core.Tests.Stack.Client
{
///
/// Unit tests for ClientBase class testing all ActivityTraceFlags combinations.
///
[TestFixture]
[Category("ClientBase")]
[SetCulture("en-us")]
[SetUICulture("en-us")]
[Parallelizable]
public class ClientBaseTests
{
private Mock? m_transportChannelMock;
private Mock? m_messageContextMock;
private RecordingLoggerProvider? m_loggerProvider;
private TestMeterListener? m_meterListener;
private ITelemetryContext? m_telemetry;
[SetUp]
public void SetUp()
{
m_loggerProvider = new RecordingLoggerProvider();
m_telemetry = DefaultTelemetry.Create(
configure => configure
.SetMinimumLevel(LogLevel.Trace)
.AddProvider(m_loggerProvider));
m_messageContextMock = new Mock();
m_messageContextMock
.Setup(m => m.Telemetry)
.Returns(m_telemetry);
m_transportChannelMock = new Mock();
m_transportChannelMock
.Setup(m => m.MessageContext)
.Returns(m_messageContextMock.Object);
m_transportChannelMock
.Setup(m => m.EndpointDescription)
.Returns(new EndpointDescription { EndpointUrl = "opc.tcp://localhost:4840" });
m_transportChannelMock
.Setup(m => m.OperationTimeout).Returns(5000);
m_meterListener = new TestMeterListener();
}
[TearDown]
public void TearDown()
{
m_meterListener?.Dispose();
m_loggerProvider?.Dispose();
}
[Test]
public void Constructor_WithValidChannel_ShouldInitializeClientBase()
{
// Arrange & Act
using var sut = new TestableClientBase(m_transportChannelMock!.Object, m_telemetry!);
// Assert
Assert.That(sut.NullableTransportChannel, Is.Not.Null);
Assert.That(sut.ActivityTraceFlags, Is.EqualTo(ClientTraceFlags.None));
}
[Test]
public void Constructor_WithNullChannel_ShouldThrowArgumentNullException()
{
// Act & Assert
Assert.Throws(() => new TestableClientBase(null!, m_telemetry!));
}
///
/// Accessing the message context after closure must report the channel
/// failure instead of dereferencing a missing transport channel.
///
[Test]
public async Task MessageContextReportsClosedChannelAsync()
{
using var sut = new TestableClientBase(m_transportChannelMock!.Object, m_telemetry!);
Assert.That(sut.MessageContext, Is.SameAs(m_messageContextMock!.Object));
await sut.TestCloseChannelAsync().ConfigureAwait(false);
Assert.That(
() => sut.MessageContext,
Throws.TypeOf()
.With.Property(nameof(ServiceResultException.StatusCode))
.EqualTo((StatusCode)StatusCodes.BadSecureChannelClosed));
}
[Test]
public async Task RequestCompletedAfterChannelCloseWithMetricsDoesNotThrowAsync()
{
using var sut = new TestableClientBase(m_transportChannelMock!.Object, m_telemetry!);
sut.ActivityTraceFlags = ClientTraceFlags.Metrics;
var request = new ReadRequest { RequestHeader = new RequestHeader() };
var response = new ReadResponse
{
ResponseHeader = new ResponseHeader
{
RequestHandle = request.RequestHeader.RequestHandle,
ServiceResult = StatusCodes.Good
}
};
await sut.TestCloseChannelAsync().ConfigureAwait(false);
Assert.DoesNotThrow(() => sut.TestRequestCompleted(request, response, "Read"));
}
///
/// Channel-backed properties report the protocol error used by generated-client cleanup.
///
[TestCase(nameof(ClientBase.MessageContext))]
[TestCase(nameof(ClientBase.Endpoint))]
[TestCase(nameof(ClientBase.EndpointConfiguration))]
public async Task ClosedChannelPropertiesReportProtocolFailureAsync(string member)
{
using var sut = new TestableClientBase(m_transportChannelMock!.Object, m_telemetry!);
await sut.TestCloseChannelAsync().ConfigureAwait(false);
Action read = member switch
{
nameof(ClientBase.MessageContext) => () => _ = sut.MessageContext,
nameof(ClientBase.Endpoint) => () => _ = sut.Endpoint,
nameof(ClientBase.EndpointConfiguration) => () => _ = sut.EndpointConfiguration,
_ => throw new ArgumentOutOfRangeException(nameof(member))
};
ServiceResultException? error = Assert.Throws(read);
Assert.That(error!.StatusCode, Is.EqualTo(StatusCodes.BadSecureChannelClosed));
}
[Test]
public void ActivityTraceFlags_None_ShouldNotRecordAnything()
{
// Arrange
using var sut = new TestableClientBase(m_transportChannelMock!.Object, m_telemetry!);
sut.ActivityTraceFlags = ClientTraceFlags.None;
var request = new ReadRequest { RequestHeader = new RequestHeader() };
var response = new ReadResponse
{
ResponseHeader = new ResponseHeader
{
RequestHandle = request.RequestHeader.RequestHandle,
ServiceResult = StatusCodes.Good
}
};
// Act
sut.TestUpdateRequestHeader(request, true, "Read");
sut.TestRequestCompleted(request, response, "Read");
// Assert
Assert.That(m_loggerProvider!.Records, Is.Empty);
Assert.That(m_meterListener!.RecordedMeasurements, Is.Empty);
}
[Test]
public void ActivityTraceFlags_Metrics_ShouldRecordMetricsOnly()
{
// Arrange
using var sut = new TestableClientBase(m_transportChannelMock!.Object, m_telemetry!);
sut.ActivityTraceFlags = ClientTraceFlags.Metrics;
var request = new ReadRequest { RequestHeader = new RequestHeader() };
var response = new ReadResponse
{
ResponseHeader = new ResponseHeader
{
RequestHandle = request.RequestHeader.RequestHandle,
ServiceResult = StatusCodes.Good
}
};
m_meterListener!.StartListening(sut.ClientBaseMeter!);
// Act
sut.TestUpdateRequestHeader(request, true, "Read");
var sw = Stopwatch.StartNew();
Thread.Sleep(TimeSpan.FromMilliseconds(100)); // simulate some duration
sw.Stop();
sut.TestRequestCompleted(request, response, "Read");
// Assert - metrics should be recorded
Assert.That(m_meterListener.RecordedMeasurements, Is.Not.Empty);
TestMeterListener.MeasurementRecord measurement =
m_meterListener.RecordedMeasurements.FirstOrDefault()!;
Assert.That(measurement!, Is.Not.Null);
Assert.That(measurement.InstrumentName, Is.EqualTo("opc.ua.client.request.duration"));
Assert.That(measurement.Value, Is.EqualTo(sw.Elapsed.TotalSeconds).Within(0.03));
// Assert - no logs should be recorded
Assert.That(m_loggerProvider!.Records
.Count(record => record.Message.Contains("Read", StringComparison.Ordinal)), Is.Zero);
}
[Test]
public void ActivityTraceFlags_Log_ShouldRecordLogsOnly()
{
// Arrange
using var sut = new TestableClientBase(m_transportChannelMock!.Object, m_telemetry!);
sut.ActivityTraceFlags = ClientTraceFlags.Log;
var request = new ReadRequest { RequestHeader = new RequestHeader() };
var response = new ReadResponse
{
ResponseHeader = new ResponseHeader
{
RequestHandle = request.RequestHeader.RequestHandle,
ServiceResult = StatusCodes.Good
}
};
// Act
sut.TestUpdateRequestHeader(request, true, "Read");
sut.TestRequestCompleted(request, response, "Read");
// Assert - compatibility logs should be recorded
Assert.That(m_loggerProvider!.Records, Has.Count.EqualTo(2));
Assert.That(m_loggerProvider.Records.Any(record =>
record.CategoryName == CoreEventIds.CoreCompatibilityCategory &&
record.EventId.Id == CoreEventIds.CoreServiceCallStart &&
record.EventId.Name == "ServiceCallStart"), Is.True);
Assert.That(m_loggerProvider.Records.Any(record =>
record.CategoryName == CoreEventIds.CoreCompatibilityCategory &&
record.EventId.Id == CoreEventIds.CoreServiceCallStop &&
record.EventId.Name == "ServiceCallStop"), Is.True);
// Assert - no metrics should be recorded
Assert.That(m_meterListener!.RecordedMeasurements, Is.Empty);
}
[Test]
public void ActivityTraceFlags_Traces_ShouldAddActivityEvents()
{
// Arrange
using var sut = new TestableClientBase(m_transportChannelMock!.Object, m_telemetry!);
sut.ActivityTraceFlags = ClientTraceFlags.Traces;
var request = new ReadRequest { RequestHeader = new RequestHeader() };
var response = new ReadResponse
{
ResponseHeader = new ResponseHeader
{
RequestHandle = request.RequestHeader.RequestHandle,
ServiceResult = StatusCodes.Good
}
};
var activityListener = new TestActivityListener();
// Act
using (Activity activity = new Activity("TestActivity").Start())
{
sut.TestUpdateRequestHeader(request, true, "Read");
sut.TestRequestCompleted(request, response, "Read");
// Assert - trace context should be added to request header
Assert.That(request.RequestHeader.AdditionalHeader.IsNull, Is.False);
Assert.That(request.RequestHeader.AdditionalHeader!.TryGetValue(
out AdditionalParametersType? additionalParams), Is.True);
Assert.That(additionalParams, Is.Not.Null);
Assert.That(additionalParams.Parameters.IsEmpty, Is.False);
KeyValuePair spanContextParam =
additionalParams.Parameters.ToList().FirstOrDefault(p => p.Key == "SpanContext")!;
Assert.That(spanContextParam, Is.Not.Null);
}
// Assert - activity events should be recorded
Assert.That(activityListener.RecordedEvents, Is.Not.Empty);
Assert.That(activityListener.RecordedEvents.Any(e => e.Name == "Started"), Is.True);
Assert.That(activityListener.RecordedEvents.Any(e => e.Name == "Completed"), Is.True);
activityListener.Dispose();
}
[Test]
public void ActivityTraceFlags_MetricsAndLog_ShouldRecordBoth()
{
// Arrange
using var sut = new TestableClientBase(m_transportChannelMock!.Object, m_telemetry!);
sut.ActivityTraceFlags = ClientTraceFlags.Metrics | ClientTraceFlags.Log;
var request = new ReadRequest { RequestHeader = new RequestHeader() };
var response = new ReadResponse
{
ResponseHeader = new ResponseHeader
{
RequestHandle = request.RequestHeader.RequestHandle,
ServiceResult = StatusCodes.Good
}
};
m_meterListener!.StartListening(sut.ClientBaseMeter!);
// Act
sut.TestUpdateRequestHeader(request, true, "Read");
Thread.Sleep(50);
sut.TestRequestCompleted(request, response, "Read");
// Assert - both metrics and logs should be recorded
Assert.That(m_meterListener.RecordedMeasurements, Is.Not.Empty);
Assert.That(m_loggerProvider!.Records, Is.Not.Empty);
}
[Test]
public void ActivityTraceFlags_TracesAndMetrics_ShouldRecordBoth()
{
// Arrange
using var sut = new TestableClientBase(m_transportChannelMock!.Object, m_telemetry!);
sut.ActivityTraceFlags = ClientTraceFlags.Traces | ClientTraceFlags.Metrics;
var request = new ReadRequest { RequestHeader = new RequestHeader() };
var response = new ReadResponse
{
ResponseHeader = new ResponseHeader
{
RequestHandle = request.RequestHeader.RequestHandle,
ServiceResult = StatusCodes.Good
}
};
var activityListener = new TestActivityListener();
m_meterListener!.StartListening(sut.ClientBaseMeter!);
// Act
using (Activity activity = new Activity("TestActivity").Start())
{
sut.TestUpdateRequestHeader(request, true, "Read");
Thread.Sleep(50);
sut.TestRequestCompleted(request, response, "Read");
}
// Assert - both traces and metrics should be recorded
Assert.That(activityListener.RecordedEvents, Is.Not.Empty);
Assert.That(m_meterListener.RecordedMeasurements, Is.Not.Empty);
activityListener.Dispose();
}
[Test]
public void ActivityTraceFlags_AllFlags_ShouldRecordEverything()
{
// Arrange
using var sut = new TestableClientBase(m_transportChannelMock!.Object, m_telemetry!);
sut.ActivityTraceFlags =
ClientTraceFlags.Metrics |
ClientTraceFlags.Traces |
ClientTraceFlags.Log;
var request = new ReadRequest { RequestHeader = new RequestHeader() };
var response = new ReadResponse
{
ResponseHeader = new ResponseHeader
{
RequestHandle = request.RequestHeader.RequestHandle,
ServiceResult = StatusCodes.Good
}
};
var activityListener = new TestActivityListener();
m_meterListener!.StartListening(sut.ClientBaseMeter!);
// Act
using (Activity activity = new Activity("TestActivity").Start())
{
sut.TestUpdateRequestHeader(request, true, "Read");
Thread.Sleep(50);
sut.TestRequestCompleted(request, response, "Read");
}
// Assert - all should be recorded
Assert.That(m_meterListener.RecordedMeasurements, Is.Not.Empty);
Assert.That(m_loggerProvider!.Records, Is.Not.Empty);
Assert.That(activityListener.RecordedEvents, Is.Not.Empty);
activityListener.Dispose();
}
[Test]
public void RequestCompleted_WithBadStatusCode_ShouldLogError()
{
// Arrange
using var sut = new TestableClientBase(m_transportChannelMock!.Object, m_telemetry!);
sut.ActivityTraceFlags = ClientTraceFlags.Log;
var request = new ReadRequest { RequestHeader = new RequestHeader() };
var response = new ReadResponse
{
ResponseHeader = new ResponseHeader
{
RequestHandle = request.RequestHeader.RequestHandle,
ServiceResult = StatusCodes.BadTimeout
}
};
// Act
sut.TestUpdateRequestHeader(request, true, "Read");
sut.TestRequestCompleted(request, response, "Read");
// Assert
RecordedLogRecord record = m_loggerProvider!.Records.Single(candidate =>
candidate.CategoryName == CoreEventIds.CoreCompatibilityCategory &&
candidate.EventId.Id == CoreEventIds.CoreServiceCallBadStop);
Assert.That(record.EventId.Name, Is.EqualTo("ServiceCallBadStop"));
Assert.That(
record.Properties["StatusCode"],
Is.EqualTo(unchecked((int)StatusCodes.BadTimeout.Code)));
}
[Test]
public void UpdateRequestHeader_ShouldSetDefaultValues()
{
// Arrange
using var sut = new TestableClientBase(m_transportChannelMock!.Object, m_telemetry!);
var request = new ReadRequest { RequestHeader = new RequestHeader() };
// Act
sut.TestUpdateRequestHeader(request, true);
// Assert
Assert.That(request.RequestHeader.RequestHandle, Is.GreaterThan(0u));
Assert.That(request.RequestHeader.Timestamp, Is.Not.EqualTo(DateTime.MinValue));
}
[Test]
public void NewRequestHandle_ShouldGenerateUniqueHandles()
{
// Arrange
using var sut = new TestableClientBase(m_transportChannelMock!.Object, m_telemetry!);
// Act
uint handle1 = sut.NewRequestHandle();
uint handle2 = sut.NewRequestHandle();
uint handle3 = sut.NewRequestHandle();
// Assert
Assert.That(handle1, Is.Not.EqualTo(handle2));
Assert.That(handle2, Is.Not.EqualTo(handle3));
Assert.That(handle1, Is.Not.EqualTo(handle3));
}
[Test]
public void ValidateResponseSurfacesRetryAfterFromAdditionalHeader()
{
var header = new ResponseHeader { ServiceResult = StatusCodes.BadServerTooBusy };
RetryAfterHeader.AttachTo(header, TimeSpan.FromSeconds(2));
ServiceResultException ex = Assert.Throws(
() => TestableClientBase.TestValidateResponse(header))!;
Assert.That(ex.StatusCode, Is.EqualTo(StatusCodes.BadServerTooBusy));
Assert.That(ex.AdditionalInfo, Does.Contain("RetryAfterMs=2000"));
}
[Test]
public void ValidateResponseIgnoresRetryAfterOnGoodResponse()
{
var header = new ResponseHeader { ServiceResult = StatusCodes.Good };
RetryAfterHeader.AttachTo(header, TimeSpan.FromSeconds(2));
Assert.DoesNotThrow(() => TestableClientBase.TestValidateResponse(header));
}
[Test]
public void ValidateResponseMergesRetryAfterIntoExistingAdditionalInfo()
{
var header = new ResponseHeader
{
ServiceResult = StatusCodes.BadServerTooBusy,
ServiceDiagnostics = new DiagnosticInfo { AdditionalInfo = "diagnostic detail" }
};
RetryAfterHeader.AttachTo(header, TimeSpan.FromSeconds(2));
ServiceResultException ex = Assert.Throws(
() => TestableClientBase.TestValidateResponse(header))!;
// The existing diagnostic AdditionalInfo is preserved and the header
// hint is merged in (not overwritten).
Assert.That(ex.AdditionalInfo, Does.Contain("diagnostic detail"));
Assert.That(ex.AdditionalInfo, Does.Contain("RetryAfterMs=2000"));
}
[Test]
public void ValidateResponseKeepsExistingRetryAfterToken()
{
var header = new ResponseHeader
{
ServiceResult = StatusCodes.BadServerTooBusy,
ServiceDiagnostics = new DiagnosticInfo { AdditionalInfo = "RetryAfterMs=5000" }
};
RetryAfterHeader.AttachTo(header, TimeSpan.FromSeconds(2));
ServiceResultException ex = Assert.Throws(
() => TestableClientBase.TestValidateResponse(header))!;
// A retry-after token already present in AdditionalInfo is kept as-is;
// the header value is not appended.
Assert.That(ex.AdditionalInfo, Is.EqualTo("RetryAfterMs=5000"));
}
///
/// Testable wrapper for ClientBase that exposes protected members.
///
private sealed class TestableClientBase : ClientBase
{
public TestableClientBase(ITransportChannel channel, ITelemetryContext telemetry)
: base(channel, telemetry)
{
}
public void TestUpdateRequestHeader(IServiceRequest request, bool useDefaults)
{
UpdateRequestHeader(request, useDefaults);
}
public void TestUpdateRequestHeader(IServiceRequest request, bool useDefaults, string serviceName)
{
UpdateRequestHeader(request, useDefaults, serviceName);
}
public void TestRequestCompleted(IServiceRequest request, IServiceResponse response, string serviceName)
{
RequestCompleted(request, response, serviceName);
}
public Task TestCloseChannelAsync()
{
return CloseChannelAsync(CancellationToken.None);
}
public static void TestValidateResponse(ResponseHeader header)
{
ValidateResponse(header);
}
public Meter? ClientBaseMeter =>
(Meter?)typeof(ClientBase)
.GetField(
"m_meter",
System.Reflection.BindingFlags.NonPublic |
System.Reflection.BindingFlags.Instance)?
.GetValue(this);
}
///
/// Test meter listener for capturing recorded measurements.
///
private sealed class TestMeterListener : IDisposable
{
private MeterListener? m_listener;
public List RecordedMeasurements { get; } = [];
public void StartListening(Meter meter)
{
m_listener = new MeterListener
{
InstrumentPublished = (instrument, listener) =>
{
// Match the meter instance, not its name: every meter
// created by the telemetry context is named after the
// assembly, so a name match would also capture e.g. the
// channel manager metrics of tests running in parallel.
if (ReferenceEquals(instrument.Meter, meter))
{
listener.EnableMeasurementEvents(instrument);
}
}
};
m_listener.SetMeasurementEventCallback(OnMeasurementRecorded);
m_listener.Start();
}
private void OnMeasurementRecorded(
Instrument instrument,
double measurement,
ReadOnlySpan> tags,
object? state)
{
RecordedMeasurements.Add(new MeasurementRecord
{
InstrumentName = instrument.Name,
Value = measurement,
Tags = tags.ToArray()
});
}
public void Dispose()
{
m_listener?.Dispose();
}
public sealed class MeasurementRecord
{
public string InstrumentName { get; set; } = string.Empty;
public double Value { get; set; }
public KeyValuePair[] Tags { get; set; } = [];
}
}
///
/// Test activity listener for capturing activity events.
///
private sealed class TestActivityListener : IDisposable
{
private readonly ActivityListener m_listener;
public Activity? CurrentActivity { get; private set; }
public List RecordedEvents { get; } = [];
public TestActivityListener()
{
m_listener = new ActivityListener
{
ShouldListenTo = _ => true,
Sample = (ref _) => ActivitySamplingResult.AllDataAndRecorded,
ActivityStarted = activity => CurrentActivity = activity,
ActivityStopped = activity =>
{
// Capture events when activity stops
if (activity != null)
{
RecordedEvents.AddRange(activity.Events);
}
}
};
ActivitySource.AddActivityListener(m_listener);
}
public ActivityListener GetListener()
{
return m_listener;
}
public void Dispose()
{
m_listener?.Dispose();
}
}
}
}