Skip to content

Commit 67f66ed

Browse files
IlyaasKIlyaasK
committed
Define the selected-surface acceptance gate
1 parent d360e8d commit 67f66ed

4 files changed

Lines changed: 104 additions & 19 deletions

File tree

‎README.md‎

Lines changed: 6 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -141,24 +141,19 @@ export KERNEL_ACC=1
141141
export KERNEL_API_KEY="..."
142142
```
143143

144-
Browser-pool acceptance tests additionally require:
144+
Browser-pool and data-source acceptance tests additionally require:
145145

146146
```sh
147147
export KERNEL_PROJECT_ID="..."
148148
```
149149

150-
Run the durable resource acceptance tests:
151-
152-
```sh
153-
go test -count=1 -timeout=30m -v ./internal/resources/browserpool -run TestAcc
154-
go test -count=1 -timeout=30m -v ./internal/resources/project -run TestAcc
155-
```
156-
157150
The tests create uniquely named durable resources and register independent
158-
cleanup. Browser-pool deletion remains `force=false`. The tests do not acquire
159-
browsers or perform runtime recovery.
151+
cleanup. Browser-pool deletion remains `force=false`. The tests do not acquire,
152+
release, or recover browsers.
153+
154+
Use the commands in the [selected-surface acceptance matrix](docs/acceptance.md).
155+
It is the source of truth for current live coverage and the pre-tag release run.
160156

161157
## Architecture
162158

163159
See [docs/architecture.md](docs/architecture.md) for package layout, Terraform semantics, testing strategy, and release planning.
164-

‎docs/acceptance.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Selected-Surface Acceptance Matrix
2+
3+
This document is the live-API release gate for the provider's selected public
4+
surface. Unit tests remain the fast default. Acceptance tests run only through
5+
explicit local opt-in or the manual GitHub Actions workflow.
6+
7+
The selected surface contains two managed resources and four read-only data
8+
sources. It does not claim coverage for future or unregistered Kernel objects.
9+
10+
## Gate Rules
11+
12+
- Set both `TF_ACC=1` and `KERNEL_ACC=1`.
13+
- Use unique `kernel-tf-*` names for every created fixture.
14+
- Register cleanup as soon as a canonical ID exists.
15+
- Verify deletion through a follow-up API read.
16+
- Keep browser-pool deletion non-forceful.
17+
- Never acquire, release, flush, invoke, or recover runtime state.
18+
- Keep live tests out of pull-request CI.
19+
- Run the complete matrix against the release commit before tagging.
20+
21+
## Environment
22+
23+
```sh
24+
export TF_ACC=1
25+
export KERNEL_ACC=1
26+
export KERNEL_API_KEY=...
27+
export KERNEL_PROJECT_ID=...
28+
export KERNEL_ALT_PROJECT_ID=... # optional second project
29+
export KERNEL_BASE_URL=... # optional non-production API
30+
```
31+
32+
`KERNEL_PROJECT_ID` is required for the browser-pool resource and all four data
33+
sources. The project resource is organization-scoped and does not require it.
34+
35+
## Matrix
36+
37+
| Surface | Package | Live scenario |
38+
| --- | --- | --- |
39+
| `kernel_project` resource | `./internal/resources/project` | Create, rename with stable ID, no-drift plan, canonical-ID import, post-import no drift, delete, and HTTP 404 verification. |
40+
| `kernel_browser_pool` resource | `./internal/resources/browserpool` | Create, durable update with stable ID, no-drift plan, provider-default and explicit project scope, bare and project-qualified import, non-force delete, and HTTP 404 verification. |
41+
| `kernel_project` data source | `./internal/datasources/project` | Create a unique project fixture, read it by ID and exact name, read the provider-default project, verify durable metadata and no drift, then delete and require coded `not_found`. |
42+
| `kernel_profile` data source | `./internal/datasources/profile` | Create a durable profile fixture through the SDK, read it by ID and exact name with explicit and default project scope, verify durable metadata and no drift, then delete and require coded `not_found`. |
43+
| `kernel_proxy` data source | `./internal/datasources/proxy` | Create a managed datacenter proxy fixture through the SDK, read it by ID and exact name with explicit and default project scope, verify durable masked metadata and no drift, then delete and require coded `not_found`. |
44+
| `kernel_extension` data source | `./internal/datasources/extension` | Upload a durable extension fixture through the SDK, read it by ID and exact name with explicit and default project scope, verify durable metadata excludes runtime usage, verify no drift, then delete and require coded `not_found`. |
45+
46+
The tests exist in the repository. That does not prove they passed against a
47+
particular release commit; the release record supplies that evidence.
48+
49+
## Commands
50+
51+
Run packages independently for fast failure isolation:
52+
53+
```sh
54+
go test -count=1 -timeout=30m -v ./internal/resources/project -run TestAcc
55+
go test -count=1 -timeout=30m -v ./internal/resources/browserpool -run TestAcc
56+
go test -count=1 -timeout=30m -v ./internal/datasources/project -run TestAcc
57+
go test -count=1 -timeout=30m -v ./internal/datasources/profile -run TestAcc
58+
go test -count=1 -timeout=30m -v ./internal/datasources/proxy -run TestAcc
59+
go test -count=1 -timeout=30m -v ./internal/datasources/extension -run TestAcc
60+
```
61+
62+
The manual `Acceptance` workflow runs the same six packages as separate matrix
63+
jobs with `fail-fast: false`. Live acceptance remains a manual pre-tag gate.
64+
65+
## Outside The Selected Surface
66+
67+
The release does not include a browser-pool data source or profile, proxy,
68+
extension, deployment, app, or API-key resources. Runtime/session operations
69+
remain outside Terraform. Unregistered surfaces are not acceptance blockers for
70+
this selected release.
71+
72+
## Release Record
73+
74+
Record the following in the release PR or release issue:
75+
76+
```text
77+
Commit:
78+
Workflow run URL:
79+
API environment:
80+
Started at:
81+
Completed at:
82+
Package results:
83+
Interrupted or timed-out jobs:
84+
Leaked-resource audit completed:
85+
```
86+
87+
Do not record credentials or secret values. A process-level timeout can bypass
88+
`t.Cleanup`; follow the cleanup procedure in
89+
[Release And Security Checklist](release.md) before rerunning or tagging.

‎docs/architecture.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -221,6 +221,9 @@ Acceptance tests must:
221221
- avoid browser/session runtime operations
222222
- exercise import and real delete behavior for each resource
223223

224+
The current registered coverage and pre-tag live run are defined by the
225+
[Selected-Surface Acceptance Matrix](acceptance.md).
226+
224227
## PR Slicing
225228

226229
PRs must be small, coherent, and shippable. No PR should rely on hidden follow-up work to keep the repo healthy.

‎docs/release.md‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -12,15 +12,13 @@ Use this checklist before publishing a Kernel Terraform provider version.
1212
- Run `terraform fmt -check -recursive examples`.
1313
- Run `go test -short -timeout=2m ./...`.
1414
- Run `go vet ./...`.
15-
- Run the complete opt-in acceptance matrix for every v1 resource and data source with real credentials before the first public release.
16-
- Browser pools: `TF_ACC=1 KERNEL_ACC=1 KERNEL_API_KEY=... KERNEL_PROJECT_ID=... go test -count=1 -timeout=30m -v ./internal/resources/browserpool -run TestAcc`.
17-
- Projects: `TF_ACC=1 KERNEL_ACC=1 KERNEL_API_KEY=... go test -count=1 -timeout=30m -v ./internal/resources/project -run TestAcc`.
18-
- The manual `Acceptance` workflow runs both packages in parallel; expand its matrix as v1 resources land and keep live tests out of normal PR CI.
15+
- Run the complete [selected-surface acceptance matrix](acceptance.md) with real credentials against the release commit.
16+
- The manual `Acceptance` workflow runs all six packages as independent matrix jobs. Keep live tests out of normal pull-request CI.
1917
- Process-level timeouts can bypass Go test cleanup. After an interrupted or hard-timeout run:
20-
1. In the Kernel dashboard or durable API, find projects and browser pools named `kernel-tf-*` that were created during the failed workflow run.
21-
2. Delete leaked browser pools first with `force=false`. If deletion conflicts with a lease, wait for the lease to end; do not force-release or recover the browser from Terraform cleanup.
22-
3. Delete a leaked project only after its child resources are gone and the organization still has another active project.
23-
4. Read each canonical resource ID and require a 404 before considering cleanup complete.
18+
1. In the Kernel dashboard or durable API, find projects, browser pools, profiles, proxies, and extensions named `kernel-tf-*` that were created during the failed workflow run.
19+
2. Delete leaked browser pools with `force=false`. If deletion conflicts with a lease, wait for the lease to end; do not force-release or recover the browser from Terraform cleanup.
20+
3. Delete other leaked project-scoped fixtures, then delete a leaked project only after its child resources are gone and the organization still has another active project.
21+
4. Read each canonical ID and require the expected not-found response before considering cleanup complete.
2422
- Verify unscoped API calls send no `X-Kernel-Project-Id` header; it is sent only when a resource-level `project_id` or the provider default resolves a project.
2523
- Confirm `terraform-registry-manifest.json` contains protocol `["6.0"]` for Terraform Plugin Framework.
2624
- Confirm the repository license before the first public release. Do not publish a public tag until `LICENSE` exists or the release owner has explicitly documented the licensing decision.

0 commit comments

Comments
 (0)