OpenParable
Skip to content
← Back to skills

Author Swa Integration Test

Testing & Quality
author-swa-integration-test

Author Swa Integration Test is an Agent Skill for testing & quality published in the dotnet/dotnet repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Author end-to-end Static Web Assets integration tests that exercise MSBuild targets through build, publish, or pack. USE FOR: writing new SWA integration tests, choosing a test asset and base class, dynamically modifying projects at runtime, selecting the right manifest to assert on, verifying the full asset pipeline (primary, compressed, endpoints). DO NOT USE FOR: unit tests of individual tasks (write those directly), baseline regeneration (use swa-baseline-regeneration), troubleshooting failures (use swa-troubleshooting).

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/dotnet/dotnet/blob/HEAD/src/sdk/.claude/skills/author-swa-integration-test/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/author-swa-integration-test, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Author SWA Integration Test

Workflow

Every SWA integration test follows four steps:

  1. Find a test asset — search the catalog in references/test-asset-catalog.md. Prefer reusing an existing asset over creating a new one. If no asset has the right project shape, pick the closest one and modify it at runtime.
  2. Copy and modify — CreateAspNetSdkTestAsset() copies the asset to an isolated temp directory. Use WithProjectChanges() for csproj modifications and File.WriteAllText() for new files (.targets, .js, .css). Each test gets its own copy — changes never affect other tests.
  3. Execute the action — build, publish, or pack the project.
  4. Assert on the right manifest — choose the manifest that answers the question you're asking (see Manifest Selection below).

Read src/StaticWebAssetsSdk/Architecture.md for the authoritative reference on asset properties, pipeline invariants, and endpoint rules.

Choose Base Class

ScenarioBase Class
Build or publish, no baseline comparisonAspNetSdkTest
Build or publish with baseline JSON comparisonAspNetSdkBaselineTest
Pack, or pack → restore → buildIsolatedNuGetPackageFolderAspNetSdkBaselineTest

Use AspNetSdkTest when you only need to check specific properties on the manifest. Use baseline classes when you need to verify the entire manifest shape matches an expected snapshot.

Dynamic Project Modification

Never modify the source test asset on disk. The test infrastructure copies assets to a temp directory — modify that copy.

Modify .csproj via XDocument

var projectDirectory = CreateAspNetSdkTestAsset("RazorAppWithP2PReference", identifier: "uniqueId")
    .WithProjectChanges((path, document) =>
    {
        if (Path.GetFileName(path) == "ClassLibrary.csproj")
        {
            document.Root.Add(new XElement("ItemGroup",
                new XElement("StaticWebAssetGroupDefinition",
                    new XAttribute("Include", "MyGroup"),
                    new XAttribute("Value", "v1"))));
            document.Root.Add(new XElement("Import",
                new XAttribute("Project", "Custom.targets")));
        }
    });

Add files at runtime

var projectDir = Path.Combine(projectDirectory.TestRoot, "ClassLibrary");
File.WriteAllText(Path.Combine(projectDir, "wwwroot", "app.js"), "console.log('hello');");
File.WriteAllText(Path.Combine(projectDir, "Custom.targets"), "<Project>...</Project>");

The identifier parameter prevents temp directory collisions when multiple tests reuse the same asset name.

Manifest Selection

ManifestFileWhat it containsWhen to use
Buildstaticwebassets.build.jsonAll assets — the complete pipeline outputSource of truth for asset properties, roles, source types. Shows the final result of pipeline execution including all variants.
Endpointsstaticwebassets.build.endpoints.jsonOnly endpoints surviving group filteringWhat the app will "see" at runtime. Use to verify endpoint routes, selectors, response headers, and that group exclusion actually removes endpoints.
Publishstaticwebassets.publish.jsonAssets scoped to publish outputChecking what ships in the published app.

The build manifest is unfiltered — it retains all asset variants so downstream consumers can select at restore time. To verify that a feature excludes content, check the endpoints manifest, not the build manifest.

How to load each

// Build manifest
var path = Path.Combine(intermediateOutputPath, "staticwebassets.build.json");
var manifest = StaticWebAssetsManifest.FromJsonBytes(File.ReadAllBytes(path));

// Endpoints manifest
var endpointsPath = Path.Combine(intermediateOutputPath, "staticwebassets.build.endpoints.json");
var endpointsManifest = JsonSerializer.Deserialize<StaticWebAssetEndpointsManifest>(
    File.ReadAllBytes(endpointsPath),
    StaticWebAssetsJsonSerializerContext.Default.StaticWebAssetEndpointsManifest);
var endpoints = endpointsManifest?.Endpoints ?? [];

Asserting the Full Pipeline

When a feature adds or modifies assets, verify the full chain — not just one layer.

Assets in the build manifest:

  • Primary asset: AssetRole == "Primary", correct RelativePath and SourceId
  • Compressed alternatives: AssetRole == "Alternative", AssetTraitName == "Content-Encoding", AssetTraitValue is gzip or br

Endpoints in the endpoints manifest:

  • Uncompressed endpoint: route matches RelativePath, Selectors.Length == 0
  • Content-negotiated endpoints: same route, Selectors[0].Name == "Content-Encoding"
  • Direct compressed routes: route ends with .gz or .br

For excluded assets: confirm the build manifest still contains them (unfiltered), but the endpoints manifest has zero matching endpoints.

For unrelated assets: verify they're unaffected — existing endpoints for other files still present.

Test Scope Checklist

Before writing tests, decide which scenarios need coverage. Ask these questions:

  • Build — Does the feature affect build-time asset resolution or the build manifest?
  • Publish — Does it change what gets published, publish paths, or the publish manifest?
  • Pack — Does it affect nupkg layout, the generated .targets, or the JSON manifest inside the package?
  • Pack → Restore → Build — Does the feature involve cross-package asset flow (e.g., a library consumed via PackageReference)?
  • P2P reference — Does it affect how assets propagate between projects via ProjectReference?
  • Incremental build — Must the feature survive modify-then-rebuild without a clean? (modify file → rebuild → assert manifest updated)
  • Group filtering — Does it involve asset groups, deferred groups, or the FilterStaticWebAssetGroups task?

Not every feature needs all of these. A change to pack layout only needs pack tests. A change to asset resolution during build needs build + possibly P2P tests. Use the checklist to avoid missing a scenario, not to mandate exhaustive coverage.

Integration Test Patterns

Build test

var build = CreateBuildCommand(projectDirectory, "AppWithP2PReference");
ExecuteCommand(build).Should().Pass();
var intermediateOutputPath = build.GetIntermediateDirectory(DefaultTfm, "Debug").ToString();

Publish test

var publish = CreatePublishCommand(projectDirectory);
ExecuteCommand(publish).Should().Pass();
// Check files in publish output directory

Pack test

var pack = CreatePackCommand(projectDirectory, "LibraryProject");
ExecuteCommand(pack).Should().Pass();
// Open .nupkg as ZipFile, inspect entries

Pack → Restore → Build

var pack = CreatePackCommand(projectDirectory, "LibraryProject");
ExecuteCommand(pack).Should().Pass();
var restore = CreateRestoreCommand(projectDirectory, "ConsumerProject");
ExecuteCommand(restore).Should().Pass();
var build = CreateBuildCommand(projectDirectory, "ConsumerProject");
ExecuteCommand(build).Should().Pass();

Incremental build

ExecuteCommand(CreateBuildCommand(projectDirectory)).Should().Pass();
File.WriteAllText(Path.Combine(projectDirectory.TestRoot, "wwwroot", "new.js"), "...");
ExecuteCommand(CreateBuildCommand(projectDirectory)).Should().Pass();
// Assert manifest reflects the new file

Reference

  • Architecture: src/StaticWebAssetsSdk/Architecture.md — asset properties, pipeline invariants, endpoint rules
  • Targets: src/StaticWebAssetsSdk/Targets/Microsoft.NET.Sdk.StaticWebAssets.targets — build pipeline
  • Test assets: test/TestAssets/TestProjects/ — see references/test-asset-catalog.md
  • Existing tests: test/Microsoft.NET.Sdk.StaticWebAssets.Tests/ — follow patterns from neighboring test classes