@stowage/conformance

Part of stowage: one typed API for object storage across S3, R2, Azure Blob, GCS and local disk.

The cases every stowage adapter and every server has to pass, as plain cases a test framework maps onto its own runner. An adapter written outside this repository passes the same cases as the ones inside it, and so does a server that answers through @stowage/http.

Install

npm install --save-dev @stowage/conformance

Write a target

A ConformanceTarget tells the suite how to construct the storage under test. createStorage returns a storage the run may write to below any prefix, constructed from outside the adapter the way a caller would construct it (spec 14.3).

import { memoryStorage } from "@stowage/adapter-memory";
import type { ConformanceTarget } from "@stowage/conformance";

export const target: ConformanceTarget = {
  name: "@stowage/adapter-memory",
  createStorage: () => memoryStorage(),
};

The optional members widen the run:

• cleanup(keyPrefix) runs once at the end, and defaults to deleteAll(keyPrefix) on a fresh storage. Every key a run writes begins with its prefix, so two runs against one bucket do not interfere.
• createStorageWithBadCredentials, createStorageWithExpiredCredentials and createStorageWithDeniedCredentials return storages whose credential the provider refuses, has expired, or accepts for reading alone.
• createStorageWithStaleCredentials(onRefresh) returns a storage whose credential the provider refuses and a fresh one passes. Its resolver answers the stale credential until it is asked with forceRefresh: true and the fresh one from then on, and calls onRefresh on every refresh, so that errors/stale-credentials can tell a refresh that recovered from a credential that was never refused.
• createStorageWithMissingBucket returns a storage bound to a bucket, container or root that does not exist and is otherwise configured as the one createStorage returns. An adapter with no bucket to miss leaves it out.

A case that needs a factory the target leaves out is reported skipped.

Fill the declaration

The suite reads what the storage supports from its capabilities, once per run, before the first case. The storage lists every name out of capabilityNames it implements, each once, and the list is fixed when it is constructed (spec 4.9). Every storage the target creates in one run declares the same; two configurations are two targets.

A case whose requires the storage declares runs its run half. A case missing a name of its requires runs the runWithout half, which checks what the storage does without the capability: most refuse the call with Unsupported naming it, presignedUrls has presignGet and presignPut absent from the storage, and a few check the weaker behavior, such as a copy whose destination reads {} (spec 14.5). An adapter refuses such a call like this:

import { StorageError } from "@stowage/core";

export function refuseUserMetadata(bucket: string): StorageError {
  return new StorageError({
    code: "Unsupported",
    message: "This storage keeps no user metadata",
    operation: "put",
    bucket,
    provider: "my-provider",
    attempts: 0,
    capability: "userMetadata",
  });
}

expectUnsupported(call, capability) asserts that refusal in a test of the adapter's own.

Run the cases

describeConformance(target, framework) maps every case onto the describe and test of the framework it is handed (spec 14.2). It runs the fast cases, and both tiers with includeSlow: true.

Vitest:

import { memoryStorage } from "@stowage/adapter-memory";
import { describeConformance } from "@stowage/conformance";
import { describe, test } from "vitest";

describeConformance(
  { name: "@stowage/adapter-memory", createStorage: () => memoryStorage() },
  { describe, test, includeSlow: true },
);

bun:test:

import { describe, test } from "bun:test";

import { memoryStorage } from "@stowage/adapter-memory";
import { describeConformance } from "@stowage/conformance";

describeConformance(
  { name: "@stowage/adapter-memory", createStorage: () => memoryStorage() },
  { describe, test },
);

Deno.test has no describe beside it, so a block becomes the leading part of each test's name:

import { memoryStorage } from "@stowage/adapter-memory";
import { describeConformance } from "@stowage/conformance";

const enclosingNames: string[] = [];

describeConformance(
  { name: "@stowage/adapter-memory", createStorage: () => memoryStorage() },
  {
    describe(name, body) {
      enclosingNames.push(name);

      try {
        body();
      } finally {
        enclosingNames.pop();
      }
    },
    test(name, body) {
      Deno.test([...enclosingNames, name].join(" > "), body);
    },
  },
);

Run the cases on workerd

workerd has no test framework. runAll(target) runs every case and returns the results, which a worker answers with for the process that started it to report:

import { memoryStorage } from "@stowage/adapter-memory";
import { runAll } from "@stowage/conformance";

export default {
  async fetch(): Promise<Response> {
    const results = await runAll({
      name: "@stowage/adapter-memory",
      createStorage: () => memoryStorage(),
    });
    const failed = results.filter((result) => result.status === "failed");

    return Response.json(results, { status: failed.length === 0 ? 200 : 500 });
  },
};

A failed result carries the error as name, message, stack and, for a StorageError, code.

Test a server

The HTTP conformance suite checks a server that answers through @stowage/http from the client's side. A case seeds and reads objects through a storage and sends its own request with fetch to the server, which serves the same objects (spec 14.8). An HttpConformanceTarget constructs that storage and names the URL of each of four routes for a key, which travels in the URL however the server routes it:

import { fromEnv, s3Storage } from "@stowage/adapter-s3";
import { describeHttpConformance, type HttpConformanceTarget } from "@stowage/conformance";
import { describe, test } from "vitest";

const origin = "http://localhost:3000";

export const target: HttpConformanceTarget = {
  name: "my-app",
  createStorage: () =>
    s3Storage({ bucket: "my-app-conformance", region: "eu-north-1", credentials: fromEnv }),
  url: (answer, key) => new URL(`/${answer}/${encodeURIComponent(key)}`, origin),
};

describeHttpConformance(target, { describe, test });

The suite fixes what each route answers with:

• serve: serveObject(storage, key, request), without options.
• redirect: redirectToObject(storage, key, request, { expiresIn: 60 }).
• upload: acceptUpload(storage, key, request, { maxSize: 1048576 }).
• presign: on POST, the JSON body { "contentType", "contentLength" } read and handed on as presignUpload(storage, key, { expiresIn: 60, maxSize: 1048576, contentType, contentLength }). Any other method is answered 405 with Allow: POST by the route itself.

The serve, redirect and upload routes hand every method the cases send, GET, HEAD, POST, PUT and DELETE, to the layer, which answers 405 itself. describeHttpConformance runs the cases inside a describe named <name> over HTTP, on Vitest, bun:test or Deno.test as above, with the same keyPrefix, cleanup and reading of the declaration. There is no runAll beside it: a server on workerd is tested from Node. A client disconnecting and flat memory are no cases, since no client observes them.

@stowage/hono is the implementation to read: one application of four routes, which @hono/node-server, Bun.serve, Deno.serve and workerd serve in this repository's CI.

Read an adapter

@stowage/adapter-memory is the implementation a third-party adapter is read against, out of the five adapters of this repository that pass these cases: @stowage/adapter-memory, @stowage/adapter-fs, @stowage/adapter-s3, @stowage/adapter-azure-blob and @stowage/adapter-gcs. It enforces the key rule exactly, declares eight of the nine capabilities, and has no network in the way. The cases themselves are written against the behavior of S3, not against it.

What the suite leaves to an adapter's own tests, such as flat memory during a large upload or the retry curve, is listed in spec 14.4.

Runtimes

Node 24 and later, Bun, Deno and workerd at the compatibility date 2026-09-01 without Node APIs. CI last ran green on Bun 1.4.3 and Deno 2.9.6.

The bundle measures 22.3 kB minified and gzipped, @stowage/core included.

Specification

docs/spec.md at @stowage/[email protected] is the contract: a caller may rely on what it states and on nothing else this package happens to export. The terms it uses and the decisions behind it are at the same tag.

License

MIT