Add docs for TeamCity service messages API

Author: NikolayPianikov

README.md

@@ -77,6 +77,8 @@ Please use our YouTrack to [report](https://youtrack.jetbrains.com/newIssue?proj
   - [Run asynchronously in parallel](#run-asynchronously-in-parallel)
   - [Cancellation of asynchronous run](#cancellation-of-asynchronous-run)
   - [Run timeout](#run-timeout)
+- TeamCity Service Messages API
+  - [TeamCity integration via service messages](#teamcity-integration-via-service-messages)
 
 ### Restore NuGet a package of newest version
 
@@ -216,3 +218,35 @@ exitCode.HasValue.ShouldBeFalse();
 
 
 
+### TeamCity integration via service messages
+
+For more details how to use TeamCity service message API please see [this](https://github.com/JetBrains/TeamCity.ServiceMessages) page. Instead of creating a root message writer like in the following example:
+``` CSharp
+using var writer = new TeamCityServiceMessages().CreateWriter(Console.WriteLine);
+```
+use this statement:
+``` CSharp
+using var writer = GetService<ITeamCityWriter>();
+```
+This sample opens a block _My Tests_ and reports about two tests:
+
+``` CSharp
+using var writer = GetService<ITeamCityWriter>();
+using (var tests = writer.OpenBlock("My Tests"))
+{
+    using (var test = tests.OpenTest("Test1"))
+    {
+        test.WriteStdOutput("Hello");
+        test.WriteImage("TestsResults/Test1Screenshot.jpg", "Screenshot");
+        test.WriteDuration(TimeSpan.FromMilliseconds(10));
+    }
+    
+    using (var test = tests.OpenTest("Test2"))
+    {
+        test.WriteFailed("Some error", "Error details");
+    }
+}
+```
+
+For more information on TeamCity Service Messages, see [this](https://www.jetbrains.com/help/teamcity/service-messages.html) page.
+

TeamCity.CSharpInteractive.Tests/Integration/ScriptRunTests.cs

@@ -366,7 +366,7 @@ public void ShouldSupportTeamCityServiceMessages()
             // When
             var result = TestTool.Run(
                 "using JetBrains.TeamCity.ServiceMessages.Write.Special;",
-                "GetService<ITeamCityBuildStatusWriter>().WriteBuildParameter(\"system.hello\", \"Abc\");");
+                "GetService<ITeamCityWriter>().WriteBuildParameter(\"system.hello\", \"Abc\");");
 
             // Then
             result.StdErr.ShouldBeEmpty(result.ToString());

TeamCity.CSharpInteractive.Tests/README_TEMPLATE.md

@@ -12,6 +12,8 @@
   - [Run asynchronously in parallel](#run-asynchronously-in-parallel)
   - [Cancellation of asynchronous run](#cancellation-of-asynchronous-run)
   - [Run timeout](#run-timeout)
+- TeamCity Service Messages API
+  - [TeamCity integration via service messages](#teamcity-integration-via-service-messages)
 
 ### Restore NuGet a package of newest version
 
@@ -151,3 +153,35 @@ exitCode.HasValue.ShouldBeFalse();
 
 
 
+### TeamCity integration via service messages
+
+For more details how to use TeamCity service message API please see [this](https://github.com/JetBrains/TeamCity.ServiceMessages) page. Instead of creating a root message writer like in the following example:
+``` CSharp
+using var writer = new TeamCityServiceMessages().CreateWriter(Console.WriteLine);
+```
+use this statement:
+``` CSharp
+using var writer = GetService<ITeamCityWriter>();
+```
+This sample opens a block _My Tests_ and reports about two tests:
+
+``` CSharp
+using var writer = GetService<ITeamCityWriter>();
+using (var tests = writer.OpenBlock("My Tests"))
+{
+    using (var test = tests.OpenTest("Test1"))
+    {
+        test.WriteStdOutput("Hello");
+        test.WriteImage("TestsResults/Test1Screenshot.jpg", "Screenshot");
+        test.WriteDuration(TimeSpan.FromMilliseconds(10));
+    }
+    
+    using (var test = tests.OpenTest("Test2"))
+    {
+        test.WriteFailed("Some error", "Error details");
+    }
+}
+```
+
+For more information on TeamCity Service Messages, see [this](https://www.jetbrains.com/help/teamcity/service-messages.html) page.
+

TeamCity.CSharpInteractive.Tests/TeamCityLogTests.cs

@@ -9,20 +9,16 @@ public class TeamCityLogTests
     {
         private readonly Mock<ISettings> _settings;
         private readonly Mock<ITeamCityLineFormatter> _lineFormatter;
-        private readonly Mock<ITeamCityBlockWriter<ITeamCityWriter>> _blockWriter;
-        private readonly Mock<ITeamCityMessageWriter> _teamCityMessageWriter;
+        private readonly Mock<ITeamCityWriter> _teamCityWriter;
         private readonly Text[] _text = {new("line1"), new("line2")};
         private readonly Mock<IStatistics> _statistics;
-        private readonly Mock<ITeamCityBuildStatusWriter> _teamCityBuildStatusWriter;
-
+        
         public TeamCityLogTests()
         {
             _settings = new Mock<ISettings>();
             _lineFormatter = new Mock<ITeamCityLineFormatter>();
             _lineFormatter.Setup(i => i.Format(It.IsAny<Text[]>())).Returns<Text[]>(i => "F_" + i.ToSimpleString());
-            _blockWriter = new Mock<ITeamCityBlockWriter<ITeamCityWriter>>();
-            _teamCityMessageWriter = new Mock<ITeamCityMessageWriter>();
-            _teamCityBuildStatusWriter = new Mock<ITeamCityBuildStatusWriter>();
+            _teamCityWriter = new Mock<ITeamCityWriter>();
             _statistics = new Mock<IStatistics>();
         }
 
@@ -32,13 +28,13 @@ public void ShouldSupportBlock()
             // Given
             var log = CreateInstance();
             var blockToken = Mock.Of<ITeamCityWriter>();
-            _blockWriter.Setup(i => i.OpenBlock("line1line2")).Returns(blockToken);
+            _teamCityWriter.Setup(i => i.OpenBlock("line1line2")).Returns(blockToken);
 
             // When
             var actualBlockToken = log.Block(_text);
 
             // Then
-            _blockWriter.Verify(i => i.OpenBlock("line1line2"));
+            _teamCityWriter.Verify(i => i.OpenBlock("line1line2"));
             actualBlockToken.ShouldBe(blockToken);
         }
 
@@ -56,7 +52,7 @@ internal void ShouldSupportError(VerbosityLevel verbosityLevel)
             log.Error(new ErrorId("id"), _text);
 
             // Then
-            _teamCityBuildStatusWriter.Verify(i => i.WriteBuildProblem("id", "line1line2"));
+            _teamCityWriter.Verify(i => i.WriteBuildProblem("id", "line1line2"));
             _statistics.Verify(i => i.RegisterError("line1line2"));
         }
 
@@ -74,7 +70,7 @@ internal void ShouldSupportWarning(VerbosityLevel verbosityLevel)
             log.Warning(_text);
 
             // Then
-            _teamCityMessageWriter.Verify(i => i.WriteWarning("line1line2"));
+            _teamCityWriter.Verify(i => i.WriteWarning("line1line2"));
             _statistics.Verify(i => i.RegisterWarning("line1line2"));
         }
 
@@ -93,7 +89,7 @@ internal void ShouldSupportInfo(VerbosityLevel verbosityLevel, bool enabled)
             log.Info(_text);
 
             // Then
-            _teamCityMessageWriter.Verify(i => i.WriteMessage("F_line1line2"), times);
+            _teamCityWriter.Verify(i => i.WriteMessage("F_line1line2"), times);
         }
 
         [Theory]
@@ -111,16 +107,14 @@ internal void ShouldSupportTrace(VerbosityLevel verbosityLevel, bool enabled)
             log.Trace("Orig", _text);
 
             // Then
-            _teamCityMessageWriter.Verify(i => i.WriteMessage($"F_{"Orig", -40}line1line2"), times);
+            _teamCityWriter.Verify(i => i.WriteMessage($"F_{"Orig", -40}line1line2"), times);
         }
 
         private TeamCityLog<string> CreateInstance() =>
             new(
                 _settings.Object,
+                _teamCityWriter.Object,
                 _lineFormatter.Object,
-                _blockWriter.Object,
-                _teamCityMessageWriter.Object,
-                _teamCityBuildStatusWriter.Object,
                 _statistics.Object);
     }
 }

TeamCity.CSharpInteractive.Tests/TeamCityOutputTests.cs

@@ -7,13 +7,13 @@ namespace TeamCity.CSharpInteractive.Tests
     public class TeamCityOutputTests
     {
         private readonly Mock<ITeamCityLineFormatter> _lineFormatter;
-        private readonly Mock<ITeamCityMessageWriter> _teamCityMessageWriter;
+        private readonly Mock<ITeamCityWriter> _teamCityWriter;
 
         public TeamCityOutputTests()
         {
             _lineFormatter = new Mock<ITeamCityLineFormatter>();
             _lineFormatter.Setup(i => i.Format(It.IsAny<Text[]>())).Returns<Text[]>(i => "F_" + i.ToSimpleString());
-            _teamCityMessageWriter = new Mock<ITeamCityMessageWriter>();
+            _teamCityWriter = new Mock<ITeamCityWriter>();
         }
 
         [Fact]
@@ -26,7 +26,7 @@ public void ShouldWriteError()
             output.WriteLine(new[] {new Text("err")});
 
             // Then
-            _teamCityMessageWriter.Verify(i => i.WriteError("F_err", null));
+            _teamCityWriter.Verify(i => i.WriteError("F_err", null));
         }
 
         [Fact]
@@ -39,12 +39,12 @@ public void ShouldWriteMessage()
             output.WriteLine(new[] {new Text("message")});
 
             // Then
-            _teamCityMessageWriter.Verify(i => i.WriteMessage("F_message"));
+            _teamCityWriter.Verify(i => i.WriteMessage("F_message"));
         }
 
         private TeamCityOutput CreateInstance() => 
             new(
                 _lineFormatter.Object,
-                _teamCityMessageWriter.Object);
+                _teamCityWriter.Object);
     }
 }

TeamCity.CSharpInteractive.Tests/TeamCityPropertiesTests.cs

@@ -8,12 +8,12 @@ namespace TeamCity.CSharpInteractive.Tests
     public class TeamCityPropertiesTests
     {
         private readonly Mock<IProperties> _properties;
-        private readonly Mock<ITeamCityBuildStatusWriter> _teamCityBuildStatusWriter;
+        private readonly Mock<ITeamCityWriter> _teamCityWriter;
 
         public TeamCityPropertiesTests()
         {
             _properties = new Mock<IProperties>();
-            _teamCityBuildStatusWriter = new Mock<ITeamCityBuildStatusWriter>();
+            _teamCityWriter = new Mock<ITeamCityWriter>();
         }
 
         [Fact]
@@ -27,10 +27,10 @@ public void ShouldSetProperty()
 
             // Then
             _properties.VerifySet(i => i["Abc"] = "Xyz");
-            _teamCityBuildStatusWriter.Verify(i => i.WriteBuildParameter("system.Abc", "Xyz"));
+            _teamCityWriter.Verify(i => i.WriteBuildParameter("system.Abc", "Xyz"));
         }
 
         private TeamCityProperties CreateInstance() =>
-            new(_properties.Object, _teamCityBuildStatusWriter.Object);
+            new(_properties.Object, _teamCityWriter.Object);
     }
 }

TeamCity.CSharpInteractive.Tests/UsageScenarios/TeamCityServiceMessages.cs

@@ -0,0 +1,47 @@
+// ReSharper disable StringLiteralTypo
+// ReSharper disable ConvertToUsingDeclaration
+namespace TeamCity.CSharpInteractive.Tests.UsageScenarios
+{
+    using System;
+    using JetBrains.TeamCity.ServiceMessages.Write.Special;
+    using Xunit;
+
+    public class TeamCityServiceMessages: Scenario
+    {
+        [SkippableFact]
+        public void Run()
+        {
+            // $visible=true
+            // $tag=3 TeamCity Service Messages API
+            // $priority=00
+            // $description=TeamCity integration via service messages
+            // $header=For more details how to use TeamCity service message API please see [this](https://github.com/JetBrains/TeamCity.ServiceMessages) page. Instead of creating a root message writer like in the following example:
+            // $header=``` CSharp
+            // $header=using var writer = new TeamCityServiceMessages().CreateWriter(Console.WriteLine);
+            // $header=```
+            // $header=use this statement:
+            // $header=``` CSharp
+            // $header=using var writer = GetService<ITeamCityWriter>();
+            // $header=```
+            // $header=This sample opens a block _My Tests_ and reports about two tests:
+            // $footer=For more information on TeamCity Service Messages, see [this](https://www.jetbrains.com/help/teamcity/service-messages.html) page.
+            // {
+            using var writer = GetService<ITeamCityWriter>();
+            using (var tests = writer.OpenBlock("My Tests"))
+            {
+                using (var test = tests.OpenTest("Test1"))
+                {
+                    test.WriteStdOutput("Hello");
+                    test.WriteImage("TestsResults/Test1Screenshot.jpg", "Screenshot");
+                    test.WriteDuration(TimeSpan.FromMilliseconds(10));
+                }
+                
+                using (var test = tests.OpenTest("Test2"))
+                {
+                    test.WriteFailed("Some error", "Error details");
+                }
+            }
+            // }
+        }
+    }
+}