Added cmdlets to manipulate build tags

Add-TeamCityBuildTag - Adds a new tag to the current build

Remove-TeamCityBuildTag - Removes a tag from the current build

+semver: major

Author: liamjpeters

CHANGELOG.md

@@ -6,6 +6,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Added cmdlets to manipulate build tags
+
+  `Add-TeamCityBuildTag` - Adds a new tag to the current build
+
+  `Remove-TeamCityBuildTag` - Removes a tag from the current build
+
 ## [0.1.0] - 2023-04-23
 
 ### Added

src/public/Add-BuildTag.ps1

@@ -0,0 +1,33 @@
+function Add-BuildTag {
+    <#
+    .SYNOPSIS
+    Adds a new tag to the current build
+
+    .DESCRIPTION
+    Adds a new tag to the current build using TeamCity service messages.
+
+    .EXAMPLE
+    Add-TeamCityBuildTag "My Custom Tag"
+
+    ##teamcity[addBuildTag 'My Custom Tag']
+
+    .NOTES
+    Added in 2023.05
+
+    .LINK
+    https://www.jetbrains.com/help/teamcity/2023.05/service-messages.html#Adding+and+Removing+Build+Tags
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Void])]
+    param (
+        [Parameter(Mandatory, Position = 0)]
+        [string]
+        # The tag to add
+        $Tag
+    )
+    if (IsRunningInTeamCity) {
+        Write-Host "##teamcity[addBuildTag '$(EscapeTeamCityBuildText $Tag)']"
+    } else {
+        Write-Host "Added build tag '$Tag'"
+    }
+}

src/public/Remove-BuildTag.ps1

@@ -0,0 +1,33 @@
+function Remove-BuildTag {
+    <#
+    .SYNOPSIS
+    Removes a tag from the current build
+
+    .DESCRIPTION
+    Removes a tag from the current build using TeamCity service messages.
+
+    .EXAMPLE
+    Remove-TeamCityBuildTag "My Custom Tag"
+
+    ##teamcity[removeBuildTag 'My Custom Tag']
+
+    .NOTES
+    Added in 2023.05
+
+    .LINK
+    https://www.jetbrains.com/help/teamcity/2023.05/service-messages.html#Adding+and+Removing+Build+Tags
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Void])]
+    param (
+        [Parameter(Mandatory, Position = 0)]
+        [string]
+        # The tag to remove
+        $Tag
+    )
+    if (IsRunningInTeamCity) {
+        Write-Host "##teamcity[removeBuildTag '$(EscapeTeamCityBuildText $Tag)']"
+    } else {
+        Write-Host "Removed build tag '$Tag'"
+    }
+}

tests/public/Add-BuildTag.Tests.ps1

@@ -0,0 +1,57 @@
+BeforeAll {
+    Import-Module "$PSScriptRoot/../../build/TeamCityLog/TeamCityLog.psd1" -Force
+}
+
+Describe 'Add-BuildTag' {
+    It 'Throws when an empty Tag is passed' {
+        {
+            Add-TeamCityBuildTag -Tag ''
+        } | Should -Throw
+    }
+
+    It "Doesn't throw when a non-empty Tag is passed" {
+        {
+            Add-TeamCityBuildTag -Tag 'My Tag' 6>&1 | Out-Null
+        } | Should -Not -Throw
+    }
+
+    It 'Allows Tag to be passed positionally' {
+        $env:TEAMCITY_VERSION = '9999.99.9'
+        $Res = Add-TeamCityBuildTag 'My Tag' 6>&1
+        $Res | Should -Be "##teamcity[addBuildTag 'My Tag']"
+    }
+
+    Context 'When Not Running in TeamCity' {
+        BeforeEach {
+            $env:TEAMCITY_VERSION = $null
+        }
+        It 'Outputs the tag but not in a service message' {
+            $Res = Add-TeamCityBuildTag -Tag 'My Tag' 6>&1
+            $Res | Should -Not -BeLike '##teamcity*'
+            $Res | Should -Be "Added build tag 'My Tag'"
+        }
+        It 'Does not escape Tag text ' {
+            $Res = Add-TeamCityBuildTag -Tag '😀' 6>&1
+            $Res | Should -Be "Added build tag '😀'"
+        }
+    }
+
+    Context 'When Running in TeamCity' {
+        BeforeEach {
+            $env:TEAMCITY_VERSION = '9999.99.9'
+        }
+        It 'Outputs Text' {
+            Mock Write-Host {} -ModuleName 'TeamCityLog'
+            Add-TeamCityBuildTag -Tag 'My Tag'
+            Should -Invoke -CommandName 'Write-Host' -Times 1 -Exactly -ModuleName 'TeamCityLog'
+        }
+        It 'Outputs the tag in a service message' {
+            $Res = Add-TeamCityBuildTag -Tag 'My Tag' 6>&1
+            $Res | Should -BeLike '##teamcity*'
+        }
+        It 'Escapes Tag Text' {
+            $Res = Add-TeamCityBuildTag -Tag 'My Tag 😀' 6>&1
+            $Res | Should -Be "##teamcity[addBuildTag 'My Tag |0xD83D|0xDE00']"
+        }
+    }
+}

tests/public/Remove-BuildTag.Tests.ps1

@@ -0,0 +1,57 @@
+BeforeAll {
+    Import-Module "$PSScriptRoot/../../build/TeamCityLog/TeamCityLog.psd1" -Force
+}
+
+Describe 'Remove-BuildTag' {
+    It 'Throws when an empty Tag is passed' {
+        {
+            Remove-TeamCityBuildTag -Tag ''
+        } | Should -Throw
+    }
+
+    It "Doesn't throw when a non-empty Tag is passed" {
+        {
+            Remove-TeamCityBuildTag -Tag 'My Tag' 6>&1 | Out-Null
+        } | Should -Not -Throw
+    }
+
+    It 'Allows Tag to be passed positionally' {
+        $env:TEAMCITY_VERSION = '9999.99.9'
+        $Res = Remove-TeamCityBuildTag 'My Tag' 6>&1
+        $Res | Should -Be "##teamcity[removeBuildTag 'My Tag']"
+    }
+
+    Context 'When Not Running in TeamCity' {
+        BeforeEach {
+            $env:TEAMCITY_VERSION = $null
+        }
+        It 'Outputs the tag but not in a service message' {
+            $Res = Remove-TeamCityBuildTag -Tag 'My Tag' 6>&1
+            $Res | Should -Not -BeLike '##teamcity*'
+            $Res | Should -Be "Removed build tag 'My Tag'"
+        }
+        It 'Does not escape Tag text ' {
+            $Res = Remove-TeamCityBuildTag -Tag '😀' 6>&1
+            $Res | Should -Be "Removed build tag '😀'"
+        }
+    }
+
+    Context 'When Running in TeamCity' {
+        BeforeEach {
+            $env:TEAMCITY_VERSION = '9999.99.9'
+        }
+        It 'Outputs Text' {
+            Mock Write-Host {} -ModuleName 'TeamCityLog'
+            Remove-TeamCityBuildTag -Tag 'My Tag'
+            Should -Invoke -CommandName 'Write-Host' -Times 1 -Exactly -ModuleName 'TeamCityLog'
+        }
+        It 'Outputs the tag in a service message' {
+            $Res = Remove-TeamCityBuildTag -Tag 'My Tag' 6>&1
+            $Res | Should -BeLike '##teamcity*'
+        }
+        It 'Escapes Tag Text' {
+            $Res = Remove-TeamCityBuildTag -Tag 'My Tag 😀' 6>&1
+            $Res | Should -Be "##teamcity[removeBuildTag 'My Tag |0xD83D|0xDE00']"
+        }
+    }
+}