diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index b0047fb..4287389 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -6,7 +6,7 @@ on: description: npm distribution tag type: choice options: [beta, latest] - default: beta + default: latest permissions: contents: read id-token: write @@ -15,6 +15,7 @@ concurrency: cancel-in-progress: false jobs: publish: + if: github.ref == 'refs/heads/main' runs-on: ubuntu-latest environment: npm steps: diff --git a/CHANGELOG.md b/CHANGELOG.md index 49ab602..e9a9695 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,14 +1,20 @@ # Changelog -## 0.1.0-beta.0 +## 0.1.0 - Add consistent annotation and function declarations across Jest and Vitest. - Add shared context creation, bounded transaction sessions, and a dedicated Jest Node environment. - Add the TypeORM adapter and preserve errors across rollback and resource release. - Verify nested fixtures, retries, timeouts, expected failures, and declaration isolation in child processes. -- Add an independent NestJS consumer covering the real database matrix and handwritten baselines. +- Include a repository-only NestJS consumer verified outside the workspace against the packed package, covering the real database matrix and handwritten baselines. - Extract the database test annotation and lifecycle manager into `@integration-testing/data`. - Include optional Prisma and node-postgres rollback adapters. - Provide independent examples with the published Testcontainers package and without containers. - Preserve original setup failures when cleanup also fails. - Verify installed ESM/CommonJS consumers, declaration exports, and real database rollback. + +Supported scope: Jest 30.1+ below 31 and Vitest 4.1; PostgreSQL through pg 8, Prisma 6.19, or +TypeORM 0.3; SQLite through Prisma 6.19. Testcontainers Integration 0.1.0 is optional and verified +through the shared launcher and manual global setup. Generated file-owned container setup, +automatic HTTP transaction propagation, other runners, and concurrent tests within a file +remain outside this release. diff --git a/README.md b/README.md index d26fe27..eee81e8 100644 --- a/README.md +++ b/README.md @@ -91,8 +91,13 @@ above. Other engines, newer client majors, and other runners are outside that ve SQL Server URL construction remains available through `/prisma/sql-server`; that helper does not establish SQL Server transaction support. -**Publication status:** Data Integration's first candidate is `0.1.0-beta.0`; it is not yet -published to npm. To use it in another application now, build and pack this repository: +**Release target: `0.1.0`.** Once this version is available on npm, install it with: + +```sh +npm install --save-dev @integration-testing/data@0.1.0 +``` + +Before publication, use a local package archive instead. Build and pack this repository: ```sh # From a checkout of this repository (Bun 1.3.5): @@ -104,10 +109,9 @@ npm pack ./packages/data --pack-destination . Copy the resulting archive to your application's `vendor` directory and install it: ```sh -npm install --save-dev ./vendor/integration-testing-data-0.1.0-beta.0.tgz +npm install --save-dev ./vendor/integration-testing-data-0.1.0.tgz ``` -After publication, the installation will be `npm install --save-dev @integration-testing/data@beta`. For the pg quick start, install the driver and TypeScript tooling: ```sh @@ -1101,7 +1105,7 @@ child processes. Consumer checks exercise real PostgreSQL/SQLite, connection los parallel files, external database URLs, and root-connection rollback verification. Package checks cover optional dependency independence and ESM/CommonJS runtime and declaration resolution. -See [release instructions](https://github.com/RolandSall/data-integration-testing/blob/4a1805f20f60ebc8fd08d6156a682d3ca400caf0/docs/releasing.md) +See [release instructions](https://github.com/RolandSall/data-integration-testing/blob/main/docs/releasing.md) for publication and trusted publishing. Read the [Testcontainers Integration documentation](https://github.com/RolandSall/testcontainers-integration#readme) for its additional infrastructure capabilities; those do not expand this package's tested transaction matrix. diff --git a/docs/releasing.md b/docs/releasing.md index 89743ba..8a72c97 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -1,38 +1,85 @@ # Publishing @integration-testing/data -The GitHub repository uses the same owner as the Testcontainers repository (`RolandSall`). -The npm package uses the same organization scope, `@integration-testing`. - -## First release - -1. Run `bun run verify`, `bun run pack:check:docker`, `bun run test:runners:minimum`, - and `bun run test:consumer` with Docker available. Repository CI, including the isolated in-repository example consumer check, must pass. - Recheck `npm view @integration-testing/data versions --json` before choosing the candidate version. - The registry returned package-not-found on September 6, 2026, so the prepared first candidate is - `0.1.0-beta.0`; this is not evidence of npm publication. -2. Authenticate to npm as a member with publish permission in `@integration-testing`. -3. From this repository, run `npm publish ./packages/data --access public --tag beta`. - This creates `@integration-testing/data@0.1.0-beta.0`. npm may require account 2FA. -4. On the npm package's settings page, add a GitHub Actions trusted publisher: - owner `RolandSall`, repository `data-integration-testing`, workflow `release.yml`, - environment `npm`, and allow the publish action. Create that GitHub environment before running the workflow. -5. Verify `npm view @integration-testing/data@beta version repository --json`. -6. Verify the published version in a clean consumer. The in-repository example gate continues - testing freshly packed output outside the workspace; examples are never included in the npm archive. - -The first publication needs an authenticated publisher; the new package cannot inherit -trusted-publisher settings from the existing Testcontainers package. Never commit npm tokens. - -## Subsequent releases - -Update the package version, run verification, commit and push to `main`, then dispatch the -Release workflow selecting `beta` or `latest`. The workflow verifies both real database examples -and the installed npm archive, checks version availability, and publishes with provenance via -GitHub OIDC. It does not need a stored npm token after trusted publishing has been configured. -Inspect the completed workflow and npm dist-tag before claiming a release is available. - -The package archive is limited to compiled outputs, declarations, README, LICENSE, and metadata. -Core imports work without a database driver, test runner, or container package installed. -Do not copy Git refs or history from an extraction source into this repository. - -Trusted publisher requirements: [npm documentation](https://docs.npmjs.com/trusted-publishers/). +The first release target is **0.1.0**, published with npm's **latest** tag. Preparing the version, +passing CI, and opening a release PR do not publish the package. + +The GitHub owner is `RolandSall` and the npm organization scope is `@integration-testing`, +the same scope as the companion Testcontainers package. + +## Verify the release candidate + +From the checkout containing the final release changes, with Node 22.22+, Bun 1.3.5, and Docker: + +```sh +bun install --frozen-lockfile +bun run verify +bun run pack:check:docker +bun run test:runners:minimum +bun run test:consumer +bun scripts/verify-release.ts +``` + +The gates check the package contents and optional dependency independence, ESM/CommonJS runtime +and declaration resolution, runner lifecycle behavior, real database rollback and failure paths, +and examples installed outside the workspace from the packed artifact. The consumer uses the +published `@integration-testing/testcontainers@0.1.0` package, not its source checkout. + +Merge the release PR only after its CI passes, then require CI on the final `main` commit to pass. +Confirm `packages/data/package.json` contains version `0.1.0`. The version-availability check +accepts only a registry 404; an authentication or network error is not evidence of availability. + +## First publication + +The registry returned package-not-found during preparation on September 11, 2026. Recheck before +publishing. The package does not inherit authentication or trusted-publisher settings from +`@integration-testing/testcontainers`. + +1. Use a clean checkout of the verified `main` commit and run the gates above. +2. Authenticate to npm with an account allowed to publish in `@integration-testing`. Check access + with `npm whoami`; use `npm login` when needed. Never commit credentials or tokens. +3. Inspect the prepared archive with `npm pack ./packages/data --dry-run`. The package includes + only `dist`, declarations, README, license, and package metadata. Examples are repository-only. +4. When ready to publish, run: + + ```sh + npm publish ./.artifacts/integration-testing-data-0.1.0.tgz --access public --tag latest + ``` + + This publishes the archive produced by the package checks. The publication is permanent for + this version, and npm may require account 2FA. Do not run this command merely to test access. +5. Check the registry rather than relying only on the command's exit status: + + ```sh + npm view @integration-testing/data@0.1.0 version dist.integrity repository --json + npm view @integration-testing/data dist-tags --json + ``` + +6. In a clean directory outside this repository, install `@integration-testing/data@0.1.0` from + npm and run the documented setup against a migrated test database. Confirm that `latest` + resolves to `0.1.0` before announcing availability. A locally packed consumer does not prove + registry installation. + +## Configure trusted publishing for subsequent releases + +After the package exists, add a GitHub Actions trusted publisher in its npm settings: + +| Setting | Value | +| --- | --- | +| Organization or user | `RolandSall` | +| Repository | `data-integration-testing` | +| Workflow filename | `release.yml` | +| Environment | `npm` | +| Allowed action | Direct publish with `npm publish` | + +The repository's `npm` GitHub environment exists. Its existence alone does not prove that the +npm trusted publisher has been configured. The workflow uses GitHub-hosted runners, Node 22.22.0, +npm 11.5.1, and `id-token: write`, matching the +[npm trusted-publishing requirements](https://docs.npmjs.com/trusted-publishers/). + +Update the version and changelog, pass the release gates, and merge to `main`. Dispatch the +Release workflow on `main`, choosing `latest` for a normal release or `beta` for a prerelease. +The workflow defaults to `latest`, skips publishing jobs on other branches, rechecks the package +and database consumers, verifies version availability, and publishes with provenance via OIDC. +It needs no stored npm publishing token once the package's trusted publisher is configured. + +Inspect the completed workflow and npm dist-tag before reporting a successful publication. diff --git a/examples/with-testcontainers/README.md b/examples/with-testcontainers/README.md index 14fd143..d7d62d8 100644 --- a/examples/with-testcontainers/README.md +++ b/examples/with-testcontainers/README.md @@ -25,5 +25,5 @@ This example therefore uses manual global setup without the generated container The container package stops the database after the run. No ports or credentials are hardcoded. To copy this project outside the workspace after publication, replace `workspace:*` with -`0.1.0-beta.0` in its `@integration-testing/data` dependency, then run `bun install` +`0.1.0` in its `@integration-testing/data` dependency, then run `bun install` and `bun run test`. The TypeScript configuration is self-contained. diff --git a/examples/without-testcontainers/README.md b/examples/without-testcontainers/README.md index e3702a8..8bb757d 100644 --- a/examples/without-testcontainers/README.md +++ b/examples/without-testcontainers/README.md @@ -22,5 +22,5 @@ URL in the setup configuration. Use your own migrations and omit database deleti your tests do not own the database. All repository operations must use the context client. To copy this project outside the workspace after publication, replace `workspace:*` with -`0.1.0-beta.0`, then run `bun install`, `bun run generate`, and `bun run test`. +`0.1.0`, then run `bun install`, `bun run generate`, and `bun run test`. The TypeScript configuration is self-contained. diff --git a/packages/data/README.md b/packages/data/README.md index d26fe27..eee81e8 100644 --- a/packages/data/README.md +++ b/packages/data/README.md @@ -91,8 +91,13 @@ above. Other engines, newer client majors, and other runners are outside that ve SQL Server URL construction remains available through `/prisma/sql-server`; that helper does not establish SQL Server transaction support. -**Publication status:** Data Integration's first candidate is `0.1.0-beta.0`; it is not yet -published to npm. To use it in another application now, build and pack this repository: +**Release target: `0.1.0`.** Once this version is available on npm, install it with: + +```sh +npm install --save-dev @integration-testing/data@0.1.0 +``` + +Before publication, use a local package archive instead. Build and pack this repository: ```sh # From a checkout of this repository (Bun 1.3.5): @@ -104,10 +109,9 @@ npm pack ./packages/data --pack-destination . Copy the resulting archive to your application's `vendor` directory and install it: ```sh -npm install --save-dev ./vendor/integration-testing-data-0.1.0-beta.0.tgz +npm install --save-dev ./vendor/integration-testing-data-0.1.0.tgz ``` -After publication, the installation will be `npm install --save-dev @integration-testing/data@beta`. For the pg quick start, install the driver and TypeScript tooling: ```sh @@ -1101,7 +1105,7 @@ child processes. Consumer checks exercise real PostgreSQL/SQLite, connection los parallel files, external database URLs, and root-connection rollback verification. Package checks cover optional dependency independence and ESM/CommonJS runtime and declaration resolution. -See [release instructions](https://github.com/RolandSall/data-integration-testing/blob/4a1805f20f60ebc8fd08d6156a682d3ca400caf0/docs/releasing.md) +See [release instructions](https://github.com/RolandSall/data-integration-testing/blob/main/docs/releasing.md) for publication and trusted publishing. Read the [Testcontainers Integration documentation](https://github.com/RolandSall/testcontainers-integration#readme) for its additional infrastructure capabilities; those do not expand this package's tested transaction matrix. diff --git a/packages/data/package.json b/packages/data/package.json index 1a78bbf..c1b0427 100644 --- a/packages/data/package.json +++ b/packages/data/package.json @@ -1,7 +1,7 @@ { "name": "@integration-testing/data", - "version": "0.1.0-beta.0", - "description": "Database integration test annotations and rollback isolation for any transaction-capable client", + "version": "0.1.0", + "description": "Transactional database integration tests for Jest and Vitest with Prisma, pg, and TypeORM", "author": "Roland Salloum", "license": "MIT", "type": "module", @@ -23,12 +23,19 @@ }, "keywords": [ "integration-testing", - "database", + "database-testing", + "transactional-testing", + "test-isolation", + "rollback", + "jest", "vitest", "prisma", + "typeorm", + "pg", "postgresql", - "testing", - "decorators" + "sqlite", + "testcontainers", + "nestjs" ], "main": "./dist/index.cjs", "module": "./dist/index.js",