parity: add LCOW HCS document parity tests between legacy and v2 builders by shreyanshjain7174 · Pull Request #2629 · microsoft/hcsshim

shreyanshjain7174 · 2026-03-13T10:29:53Z

Summary

Adds parity tests that compare the HCS ComputeSystem documents produced by the
legacy shim pipeline and the new v2 LCOW builder (lcow.BuildSandboxConfig).

Both paths receive the same inputs — annotations, shim options, and devices —
so the resulting documents should be structurally identical.

How it works

Each test case feeds identical inputs to both pipelines:

Legacy: OCI spec + runhcsopts.Options
  → oci.UpdateSpecFromOptions
  → oci.ProcessAnnotations
  → oci.SpecToUVMCreateOpts → *OptionsLCOW
  → uvm.VerifyOptions
  → uvm.NewUtilityVMForDoc → uvm.MakeLCOWDoc → HCS document

V2: vm.Spec + runhcsopts.Options
  → lcow.BuildSandboxConfig → HCS document + SandboxOptions

Changes

internal/uvm/create_lcow.go: Export MakeLCOWDoc and VerifyOptions for
use in parity tests. These generate the HCS document and validate options
without creating a VM or calling HCS.
internal/uvm/types.go: Add NewUtilityVMForDoc constructor — creates a
minimal UtilityVM with the fields needed by MakeLCOWDoc. Must live in the
uvm package because all UtilityVM fields are unexported.
internal/uvm/create.go, internal/uvm/create_wcow.go: Rename
verifyOptions → VerifyOptions (exported).
.github/workflows/ci.yml: Include test/parity/vm/ in the non-functional
test step.
test/parity/vm/ (new vmparity package):
- doc.go — package documentation
- hcs_lcow_document_creator_test.go — helper functions that wire the legacy
  and v2 pipelines: buildLegacyLCOWDocument, buildV2LCOWDocument,
  setupBootFiles, jsonToString
- lcow_doc_test.go — 3 document parity tests, 5 sandbox option field checks,
  and a checkSandboxOptionsParity helper for extensibility

Test cases

Test	What it validates
CPU + memory + QoS + MMIO + CPUGroup	Annotation-driven topology changes propagate identically
memory + MMIO + QoS (overcommit off)	Overcommit disabled + storage QoS match in both documents
shim options CPU/memory + annotation QoS	Shim-level options merged with annotation QoS
SandboxOptions field parity (5 checks)	NoWritableFileShares, EnableScratchEncryption, PolicyBasedRouting, FullyPhysicallyBacked, VPMEMMultiMapping

Results

All 8 tests pass (3 document + 5 field).

More permutations (boot modes, VPCI devices, VPMem sizes, NUMA topology) will
be added in follow-up PRs once this foundation is reviewed and merged.

rawahars

Left comments.

Also, please ensure that the comments are verbose and easy to understand.

test/parity/doc.go

internal/uvm/create_lcow.go

test/parity/lcow_doc_test.go

test/parity/helpers_test.go

test/parity/lcow_doc_test.go

Address review feedback from PR microsoft#2629. Major changes: Source changes (internal/uvm/): - Export VerifyOptions, MakeLCOWDoc, MakeLCOWSecurityDoc as public functions so they can be called directly from the test package. - Remove MakeLCOWDocument composite wrapper — test assembles the pipeline itself using the exported primitives. - Add NewUtilityVMForDoc constructor in types.go. This is needed because MakeLCOWDoc takes a *UtilityVM parameter and reads its unexported fields (scsiControllerCount, vpmemMaxCount, etc). The test cannot set these fields directly from outside the package, so NewUtilityVMForDoc creates a minimal UtilityVM with only the fields needed for document generation. - Original source code comments preserved — only function names changed from lowercase to uppercase. Test changes (test/parity/vm/): - Moved from test/parity/ to test/parity/vm/ for future WCOW support. - Removed functional build tag — these are not functional tests. - Removed all normalization (nil-vs-empty, map sorting, owner zeroing). cmp.Diff handles maps natively. Real differences are not masked. - Merged pipeline helpers into hcs_document_creator_test.go. - Removed helpers_test.go — setupBootFiles and jsonToString moved inline. - Generic doc.go that covers both LCOW and future WCOW. - All test cases explicitly populate every field (CPU, memory, MMIO, QoS, CPUGroupID) so comparison always checks populated values, not defaults. - Use maps.Clone for annotation copying. - Use testing.Verbose() to gate debug logging. - Descriptive error messages throughout. All 8 tests pass (3 document parity + 5 field parity). Signed-off-by: Shreyansh Sancheti <shsancheti@microsoft.com>

shreyanshjain7174 · 2026-03-16T07:01:53Z

Thanks for the thorough review @rawahars — really appreciate the detailed feedback. Pushed a full restructure addressing all 26 comments:

Source changes:

Removed MakeLCOWDocument composite wrapper as suggested. Instead exported the primitives: VerifyOptions, MakeLCOWDoc, MakeLCOWSecurityDoc.
Added NewUtilityVMForDoc constructor in types.go — this is needed because MakeLCOWDoc takes *UtilityVM and reads unexported fields like scsiControllerCount, vpmemMaxCount etc. The test can't set those from outside the package, so this constructor creates a minimal UtilityVM with only the doc-generation fields. Open to suggestions if there's a cleaner way to expose this.

Test restructure:

Moved to test/parity/vm/ for future WCOW support
Removed functional build tag
Removed all normalization — cmp.Diff handles maps, real differences aren't masked
Merged pipeline files into single hcs_document_creator_test.go
setupBootFiles and jsonToString live in the creator file
Generic doc.go following the pattern from builder/vm/lcow/doc.go
testing.Verbose() gated logging

Key finding during testing: The v2 builder unconditionally initializes CpuGroup (topology.go line 54) even when cpuGroupID is empty, while legacy only sets it when non-empty. All test cases now explicitly set CPUGroupID so both paths populate the field — all 8 tests pass (3 document + 5 field parity).

internal/uvm/create_lcow.go

internal/uvm/types.go

test/parity/vm/doc.go

test/parity/vm/hcs_lcow_document_creator_test.go

rawahars · 2026-03-16T16:12:08Z

test/parity/vm/lcow_doc_test.go

+func TestLCOWSandboxOptionsFieldParity(t *testing.T) {
+	bootDir := setupBootFiles(t)
+
+	tests := []struct {


In order to test the fields which are part of SandboxOptions, do you need runhcsoptions too?

Yes — both pipelines require runhcsopts.Options to function. The legacy path needs it for oci.UpdateSpecFromOptions and boot file resolution, the v2 path needs it as a required parameter to BuildSandboxConfig (reads SandboxPlatform and BootFilesRootPath). The SandboxOptions fields themselves come from annotations, but the pipeline that produces them won't run without shimOpts.

rawahars · 2026-03-16T16:13:08Z

test/parity/vm/lcow_doc_test.go

+				t.Fatalf("failed to build v2 LCOW document: %v", err)
+			}
+
+			checks := []struct {


nit: Maybe define this outside the inner t.Run. It becomes confusing inside the loop.
Also, I imagine you would need to test other fields too including Confidential Options.

- Rename package from 'vm' to 'vmparity' for clarity - Rename hcs_document_creator_test.go to hcs_lcow_document_creator_test.go to distinguish LCOW-specific helpers from future WCOW - Revert MakeLCOWSecurityDoc back to unexported (not used in tests) - Simplify doc.go to match codebase convention (minimal, no file layout) - Update NewUtilityVMForDoc comment explaining why it must stay in uvm package (UtilityVM fields are unexported) Signed-off-by: Shreyansh Sancheti <shsancheti@microsoft.com>

Signed-off-by: Shreyansh Sancheti <shsancheti@microsoft.com>

rawahars

LGTM 🚢

shreyanshjain7174 requested a review from a team as a code owner March 13, 2026 10:29

shreyanshjain7174 requested a review from rawahars March 13, 2026 10:42

rawahars requested changes Mar 14, 2026

View reviewed changes

shreyanshjain7174 force-pushed the parity/lcow-document-test branch from 44a4cea to b6a131c Compare March 16, 2026 07:01

shreyanshjain7174 requested a review from rawahars March 16, 2026 08:35

This was referenced Mar 16, 2026

parity: add LCOW document permutation tests shreyanshjain7174/hcsshim#1

Closed

parity: add LCOW document permutation tests #2631

Open

rawahars requested changes Mar 16, 2026

View reviewed changes

shreyanshjain7174 force-pushed the parity/lcow-document-test branch from 99c900d to 3f1b638 Compare March 17, 2026 07:24

parity: add LCOW HCS document parity tests for v2 builder validation

72d9362

Signed-off-by: Shreyansh Sancheti <shsancheti@microsoft.com>

shreyanshjain7174 force-pushed the parity/lcow-document-test branch from 3f1b638 to 72d9362 Compare March 17, 2026 07:26

shreyanshjain7174 requested a review from rawahars March 17, 2026 08:29

rawahars approved these changes Mar 17, 2026

View reviewed changes

Conversation

shreyanshjain7174 commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

How it works

Changes

Test cases

Results

Uh oh!

rawahars left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

shreyanshjain7174 commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rawahars Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

shreyanshjain7174 Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

rawahars Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

rawahars left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

shreyanshjain7174 commented Mar 13, 2026 •

edited

Loading

shreyanshjain7174 commented Mar 16, 2026 •

edited

Loading