Skip to content

Served-assets smoke test

The big picture: a container image for a single-page app (SPA) can build, scan clean, and pass every unit test, and still show users a blank screen. Two separate failures cause it, and nothing in a build-test-push pipeline looks for either.

Why it matters: both failures look healthy from every angle except a browser. The HTTP status is 200, the pod is Ready, the image passed its scan. Only a request for the actual JavaScript file, with its content type checked, shows the problem.

How it works:

  • Failure 1, the image does not serve its own assets. A wrong base path, a missing hashed file, or a web-server rule that does not match /assets/ leaves index.html pointing at files the image cannot deliver.
  • Failure 2, version skew during a rolling update. A browser tab still holding the previous release’s index.html asks the new pods for hashed files they no longer have.
  • The fix is two checks, run before push: boot the image and fetch every asset its index.html names; then also require the previous release’s hashed files to be served.

Failure 1: the image cannot serve its own assets

Section titled “Failure 1: the image cannot serve its own assets”

The sneaky version is the SPA fallback. Most SPA web servers are configured to answer any unknown path with index.html so client-side routing works (nginx: try_files $uri $uri/ /index.html). A request for a hashed file that is not there then returns HTTP 200 with Content-Type: text/html. The browser expects JavaScript for a <script type="module">, rejects the HTML under strict MIME checking, and the app never starts. Every signal short of a browser reads green.

Run it against the image you just built, booted locally in CI, before it is pushed:

  1. Fetch <base_url>/ and collect every same-origin <script src>, <link rel="modulepreload"> and <link rel="stylesheet">.
  2. Fetch each one. Pass only on HTTP 2xx, a non-empty body, and a content type the browser will accept. The type expected is chosen by the file’s extension (JavaScript for .js/.mjs, text/css for .css); any other extension only has to not be text/html. The HTML check is what catches the SPA fallback.
  3. Fail when the page names zero assets. An empty list would otherwise pass vacuously against a JSON error page or a default web-server welcome page.
  4. Request a path that cannot exist, next to the first asset (so an app that serves from /static/ is probed under /static/). It must come back 4xx. A 2xx means the fallback is masking missing files and every other check is suspect; a 3xx or 5xx also fails, because the server is not answering “no such file” cleanly.
  5. Skip cross-origin references and say so; never fetch them.

Root-absolute paths (/app/assets/a.js) resolve against the origin and relative ones against the page URL, so an app built with a sub-path base (Vite base: '/app/') works when you point the script at http://host/app.

Limits to know about. Inline module scripts, <link rel="icon"> and similar tags are not checked, and neither is anything only JavaScript loads at run time (fonts, images). index.html names only what it loads eagerly, so a lazy import() chunk that is never preloaded is invisible to it. If your bundler can emit a manifest of every file it produced (Vite’s build.manifest does), fetch each file named there as well. And a green result proves the files are served, not that the app runs; it complements an end-to-end test rather than replacing one.

Failure 2: version skew during a rolling update

Section titled “Failure 2: version skew during a rolling update”

Bundlers name output files by content hash (/assets/app-3f9a1c.js), so each release has a different set of files. During and after an upgrade there are two directions of skew:

Direction Who hits it How long it lasts
Backward: a tab holds release N’s index.html and asks an N+1 pod for an N file Every tab opened before the upgrade, the next time it loads a route it has not visited yet Indefinitely after the rollout ends, until that tab reloads
Forward: a client got N+1’s index.html from a new pod and asks an old N pod for an N+1 file Clients that load the app mid-rollout Only while both versions serve, seconds to minutes

Backward skew is the long tail, and it also hits single-replica installs, because replacing the one pod is enough to strand every open tab.

  • Make a missing asset a real 404, not a 200 HTML page: serve /assets/ with try_files $uri =404. A failed load is then a failed load the client can detect.
  • Reload once on a failed chunk load. In Vite, handle the vite:preloadError event and reload the page at most once per time window, so a stale tab heals itself without looping.
  • Ship the previous release’s hashed assets inside the new image. This is the only one that removes the failure instead of recovering from it. Add a build argument that names the previous release’s image (by digest, so the build is reproducible). The build copies only the files that release’s build produced into assets/, then lays the current build on top. Content-hashed names cannot collide with different content, so overwrite order does not matter. Copy by the prior build’s file list, not its whole assets/ directory: each prior image already carries its own predecessor, so copying the directory would accumulate every release forever. Only assets/ is inherited; index.html and every other root file always come from the current build.

Resolve it mechanically in the publish pipeline, never by hand:

  • the latest published tag in the current major.minor line, if one exists;
  • otherwise the latest published tag of the previous line (the first 1.3.0 inherits from the last 1.2.x);
  • skipping releases that were withdrawn.

The image carries only the one most recent prior release, so the guarantee is narrower than “any sequential upgrade”. If 1.2.0 and then 1.2.1 were published and a user upgrades from 1.2.0 straight to 1.3.0, the new image carries 1.2.1’s files, not 1.2.0’s; a tab opened on 1.2.0 falls back to the once-per-window reload from the mitigations above. This affects anyone who skips an intermediate release in the same line, as well as any larger jump such as 1.2 to 1.9. State this limit in your own upgrade docs. Carrying more releases means a shared volume or an object store, at a real operational cost.

Make the guarantee a check, not a belief. Extract the previous release’s asset list (from its build manifest, or from listing its assets/ directory) and require every file in it to be served by the new image, with the same status and content-type rules as above. Decide up front what an unresolvable previous release means: the first release ever published has none (the template prints prior-release check: skipped (PRIOR_ASSETS_FILE unset) and does not fail), but a pipeline that knows a previous release exists must set the variable and should fail when it cannot resolve the file, otherwise a lookup error silently turns the gate off.

To test the forward direction you need two versions serving at once, which means driving a real rolling update and repeating the fetch several times, since each new connection can land on a different pod. A 404 on a new release’s file in that window is expected, so a check that runs mid-rollout needs a mode that tolerates it. This is worth building only if your deployment is multi-replica and has an upgrade drill.

Blueprint ships scripts/templates/check-served-assets.sh, a POSIX sh script that needs only curl and a URL. It implements the five checks under Failure 1 and takes an optional PRIOR_ASSETS_FILE for the previous-release gate. The file holds one asset path per line, and each path must start with / (anything else exits 2 with an error). Blank or whitespace-only lines, # comment lines and CRLF line endings are ignored, surrounding whitespace is trimmed, and a last line with no newline is still checked. A file that is missing, empty, or holds no paths fails the run rather than passing with nothing checked:

Terminal window
# boot the image you just built, then:
sh scripts/templates/check-served-assets.sh http://127.0.0.1:8080
# also require the previous release's files to be served
PRIOR_ASSETS_FILE=prior-assets.txt sh scripts/templates/check-served-assets.sh http://127.0.0.1:8080

Blueprint stays stack-agnostic, so the script deliberately does not do the parts that depend on your tooling: building and booting the image, reading a bundler manifest, resolving the previous release’s image, or extracting its file list. Those are a few lines in your own CI job. The script is a template: copy it into your project and wire it into your build job. It runs --self-test in Blueprint’s tooling-self-tests job against a local fixture server, including the SPA-fallback case, so the check itself is proven able to fail.