Skip to content

Commit c7d939e

Browse files
paulmedynskipaulmedynski
committed
- Updated stage documentation to be complete and accurate.
- Moved validate symbols script into scripts/ .
1 parent a5aa5a1 commit c7d939e

9 files changed

Lines changed: 102 additions & 128 deletions

File tree

‎eng/pipelines/onebranch/jobs/validate-symbols-job.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ jobs:
6464
displayName: Verify ${{ pkg.packageName }} on ${{ server.name }}
6565
inputs:
6666
pwsh: true
67-
filePath: eng/pipelines/onebranch/jobs/validate-symbols.ps1
67+
filePath: eng/pipelines/onebranch/scripts/validate-symbols.ps1
6868
arguments: >
6969
-ArtifactPath "$(Pipeline.Workspace)\${{ pkg.artifactName }}"
7070
-ExtractPath "$(extractRoot)\${{ pkg.packageName }}"

‎eng/pipelines/onebranch/scripts/tests/README.md‎

Lines changed: 57 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,79 @@
1-
# Publish-Symbols Tests
1+
# OneBranch Script Tests
22

3-
Pester tests for the `publish-symbols.ps1` script used by the symbol publishing pipeline step.
3+
This directory contains [Pester](https://pester.dev/) tests for PowerShell
4+
scripts used by the OneBranch pipelines.
45

56
## Prerequisites
67

7-
- PowerShell 5.1+ or PowerShell 7+
8-
- [Pester v5](https://pester.dev/) (`Install-Module Pester -MinimumVersion 5.0 -Scope CurrentUser`)
8+
| Tool | Version | Install |
9+
| ---- | ------- | ------- |
10+
| PowerShell (pwsh) | 7.2+ | [Install PowerShell](https://learn.microsoft.com/powershell/scripting/install/installing-powershell) |
11+
| Pester | 5.x | `Install-Module Pester -Force -Scope CurrentUser -SkipPublisherCheck` |
912

10-
## Running the Tests
13+
## Running tests
1114

12-
From this directory:
15+
From the repository root:
1316

1417
```powershell
15-
Invoke-Pester ./publish-symbols.Tests.ps1
18+
pwsh -c "Invoke-Pester ./eng/pipelines/onebranch/scripts/tests/ -Output Detailed"
1619
```
1720

18-
Or from the repository root:
21+
Run a single test file:
1922

2023
```powershell
21-
Invoke-Pester ./eng/pipelines/onebranch/scripts/tests/
24+
pwsh -c "Invoke-Pester ./eng/pipelines/onebranch/scripts/tests/publish-symbols.Tests.ps1 -Output Detailed"
25+
pwsh -c "Invoke-Pester ./eng/pipelines/onebranch/scripts/tests/validate-symbols.Tests.ps1 -Output Detailed"
2226
```
2327

24-
For detailed output:
28+
## Writing tests
29+
30+
### File naming
31+
32+
Test files must follow Pester naming conventions:
33+
34+
```text
35+
<ScriptUnderTest>.Tests.ps1
36+
```
37+
38+
### Locating the script under test
39+
40+
When scripts and tests are siblings under `scripts/` and `scripts/tests/`,
41+
reference scripts relative to `$PSScriptRoot`:
42+
43+
```powershell
44+
BeforeAll {
45+
$Script:ScriptPath = Join-Path $PSScriptRoot '..' 'my-script.ps1'
46+
}
47+
```
48+
49+
### Testing scripts that use `exit`
50+
51+
Pipeline scripts commonly use `exit` for control flow. To validate exit codes,
52+
run scripts as child processes with `Start-Process`:
2553

2654
```powershell
27-
Invoke-Pester ./publish-symbols.Tests.ps1 -Output Detailed
55+
$proc = Start-Process -FilePath 'pwsh' `
56+
-ArgumentList @('-NoProfile', '-NonInteractive', '-File', $scriptPath, <args...>) `
57+
-NoNewWindow -Wait -PassThru `
58+
-RedirectStandardOutput $stdoutFile `
59+
-RedirectStandardError $stderrFile
60+
61+
$proc.ExitCode | Should -Be 0
2862
```
2963

30-
## Test Coverage
64+
### Mocking external tools
65+
66+
When a script calls external tools (for example `symchk.exe`, `az`, or
67+
`Invoke-RestMethod`), mock those calls in tests. See
68+
`validate-symbols.Tests.ps1` and `publish-symbols.Tests.ps1`.
69+
70+
## Test inventory
3171

32-
| Area | What's tested |
33-
| --------------------- | ---------------------------------------------------------------- |
34-
| Parameter validation | Empty strings rejected for all mandatory parameters |
35-
| URL construction | Base URL, register URL, request URL built from parameters |
36-
| Request bodies | Registration body, default publish flags, flag overrides |
37-
| Error handling | Token failure, registration failure, publish failure, status failure — all verify expanded URI in error message |
38-
| Status validation | Detects Failed/Cancelled results, respects PublishToInternal/PublishToPublic flags, passes on Succeeded/Pending |
72+
| Test file | Script under test | What it covers |
73+
| --------- | ----------------- | -------------- |
74+
| `publish-symbols.Tests.ps1` | `scripts/publish-symbols.ps1` | Parameter validation, URL construction, request bodies, status validation, error handling |
75+
| `validate-symbols.Tests.ps1` | `scripts/validate-symbols.ps1` | Syntax validation, package discovery/extraction, symchk detection, retry logic |
3976

4077
## Notes
4178

42-
- All external calls (`az`, `Invoke-RestMethod`) are mocked — no network access or Azure credentials are required.
43-
- Tests validate the script at `../publish-symbols.ps1` relative to this directory.
79+
- Tests for `publish-symbols.ps1` mock all external calls (`az`, `Invoke-RestMethod`), so no network access or Azure credentials are required.

eng/pipelines/onebranch/tests/validate-symbols.Tests.ps1 renamed to eng/pipelines/onebranch/scripts/tests/validate-symbols.Tests.ps1

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
# Run with: pwsh -c "Invoke-Pester ./validate-symbols.Tests.ps1 -Output Detailed"
1010

1111
BeforeAll {
12-
$Script:ScriptPath = Join-Path $PSScriptRoot '..' 'jobs' 'validate-symbols.ps1'
12+
$Script:ScriptPath = Join-Path $PSScriptRoot '..' 'validate-symbols.ps1'
1313

1414
# Common parameters reused across tests.
1515
$Script:CommonParams = @{

eng/pipelines/onebranch/jobs/validate-symbols.ps1 renamed to eng/pipelines/onebranch/scripts/validate-symbols.ps1

File renamed without changes.

‎eng/pipelines/onebranch/stages/build-stages.yml‎

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,18 +4,25 @@
44
# See the LICENSE file in the project root for more information. #
55
#################################################################################
66

7-
# Unified build stages template for sqlclient OneBranch pipelines. Consumed by both the official
8-
# and non-official pipeline definitions.
7+
# Unified build stages template for SqlClient OneBranch pipelines. Consumed by
8+
# both the official and non-official pipeline definitions.
99
#
1010
# Stages defined by this template and their controlling parameters:
1111
#
12-
# Stage | Condition | Packages
13-
# -----------------------|------------------------------------------|-----------------------------------
14-
# build_independent | Always (at least one job when any | Logging (buildSqlClient || buildAKVProvider)
15-
# | build* param is true) | SqlServer (buildSqlServerServer)
16-
# build_abstractions | buildSqlClient | Abstractions
17-
# build_dependent | buildSqlClient | SqlClient, Azure
18-
# build_addons | buildAKVProvider && buildSqlClient | AKV Provider
12+
# Stage | Condition | Produced packages
13+
# -------------------|----------------------------------------|-----------------------------------
14+
# build_independent | Always emitted | Logging (buildSqlClient ||
15+
# | | buildAkvProvider)
16+
# | | SqlServer (buildSqlServerServer)
17+
# build_abstractions | buildSqlClient | Abstractions
18+
# build_dependent | buildSqlClient | SqlClient, Azure
19+
# build_addons | buildAkvProvider && buildSqlClient | AKV Provider
20+
#
21+
# Notes:
22+
# - build_independent is always present so downstream stages can depend on a
23+
# stable stage name; individual jobs inside it are compile-time conditional.
24+
# - build_dependent stage name is intentionally stable because downstream
25+
# templates depend on it by name.
1926
#
2027
# This template depends on the following runtime (i.e. macro expansion) variables being defined:
2128
#

‎eng/pipelines/onebranch/stages/publish-symbols-stage.yml‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,14 @@
44
# See the LICENSE file in the project root for more information. #
55
#################################################################################
66

7-
# Unified symbols publishing stage template for sqlclient OneBranch pipelines.
7+
# Unified symbols publishing stage template for SqlClient OneBranch pipelines.
88
# Consumed by both the official and non-official pipeline definitions.
99
#
10-
# This stage publishes PDB symbol files to the internal and public symbol servers.
11-
# Each package's PDBs are published in a separate job to maintain unique naming and
12-
# versioning information per package.
10+
# Stage defined by this template:
11+
# - publish_symbols (emitted only when publishSymbols is true)
12+
#
13+
# This stage publishes PDB symbol files for each built package in separate jobs
14+
# to preserve package-specific naming and versioning metadata.
1315
#
1416
# PDBs are expected to be located under the 'symbols/' directory at the root of
1517
# each build artifact, with target framework subdirectories preserved by the build

‎eng/pipelines/onebranch/stages/release-stage.yml‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,17 @@
44
# See the LICENSE file in the project root for more information. #
55
#################################################################################
66
#
7-
# Unified release stage template for dotnet-sqlclient OneBranch pipelines. Consumed by both the
8-
# official and non-official pipeline definitions.
7+
# Unified release stage template for dotnet-sqlclient OneBranch pipelines.
8+
# Consumed by both the official and non-official pipeline definitions.
99
#
1010
# Stages defined by this template and their controlling parameters:
1111
#
12-
# Stage | Condition | Packages
13-
# -----------------------|--------------------------------------------------|-----------------------------
14-
# release_<suffix> | Any release* parameter is true | One job per enabled release*
15-
# | (releaseSqlServerServer, releaseLogging, | parameter
16-
# | releaseAbstractions, releaseSqlClient, |
17-
# | releaseAzure, releaseAKVProvider) |
12+
# Stage | Condition | Packages
13+
# -----------------------|-------------------------------------------------|------------------------------
14+
# release_<stageNameSuffix> | Any release* parameter is true | One publish job per enabled
15+
# | (releaseSqlServerServer, releaseLogging, | release parameter
16+
# | releaseAbstractions, releaseSqlClient, |
17+
# | releaseAzure, releaseAkvProvider) |
1818
#
1919
# The isOfficial flag controls release-stage behaviour:
2020
# - Official → Production environment, approval gate.

‎eng/pipelines/onebranch/stages/validation-stage.yml‎

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,21 @@
44
# See the LICENSE file in the project root for more information. #
55
#################################################################################
66

7-
# Validation stage template. Runs after build stages complete and verifies the signed SqlClient
8-
# package as well as (optionally) symbol availability on public and internal symbol servers.
7+
# Validation stage template. Runs after build stages complete and verifies the
8+
# signed SqlClient package, and optionally validates symbol availability.
99
#
10-
# This template defines the validation stage.
10+
# Stage defined by this template:
11+
# - validation (always emitted)
1112
#
12-
# The validate-symbols-job checks the following packages depending on parameters:
13-
# - SqlServer - when buildSqlServerServer is true.
14-
# - Logging, Abstractions, SqlClient, Azure - when buildSqlClient is true.
15-
# - AKV Provider - when buildSqlClient and buildAKVProvider are true.
13+
# Jobs included in the validation stage:
14+
# - validate-signed-package-job when buildSqlClient is true
15+
# - validate-symbols-job when publishSymbols is true
16+
#
17+
# The validate-symbols-job checks the following packages depending on
18+
# parameters:
19+
# - SqlServer when buildSqlServerServer is true.
20+
# - Logging, Abstractions, SqlClient, Azure when buildSqlClient is true.
21+
# - AKV Provider when buildSqlClient and buildAKVProvider are true.
1622

1723
parameters:
1824
# ── General parameters ─────────────────────────────────────────────────

‎eng/pipelines/onebranch/tests/README.md‎

Lines changed: 0 additions & 77 deletions
This file was deleted.

0 commit comments

Comments
 (0)