gsadmin/certctl
1
0
Fork 0
mirror of https://github.com/shankar0123/certctl.git synced 2026-06-07 17:51:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Phase 5 — testing-guide.md prune (8268 → 0 lines, content dispersed)

Browse Source 
Per Phase 1 audit at cowork/docs-overhaul-phase-1-audit-2026-05-04/
and the section-by-section plan in testing-guide-tumor.md.

testing-guide.md was 30% of all docs/ content (8268 lines) but was
integration test code written in markdown, not operator documentation.
The audit's tumor analysis disposed of every Part:
  - ~65% DELETE (test cases that already exist in code)
  - ~22% MOVE to inline test code
  - ~8% KEEP-COMPRESSED into focused operator-runbook docs
  - Title + contents + release sign-off ~5% KEEP

This commit ships the KEEP-COMPRESSED dispersal:

  docs/contributor/qa-prerequisites.md (NEW, ~120 lines):
    From testing-guide.md "Prerequisites" section. Stack boot procedure,
    demo data baseline, reference IDs operators reuse across QA docs.

  docs/contributor/gui-qa-checklist.md (NEW, ~105 lines):
    From testing-guide.md "Part 35: GUI Testing". Manual GUI verification
    pass for release sign-off. 25-row table covering every dashboard page.

  docs/contributor/release-sign-off.md (NEW, ~130 lines):
    From testing-guide.md "Release Sign-Off" section (originally 1009
    lines of per-test detail tables). Compressed to a release-day
    checklist organized by gate category: code state, automated gates,
    manual QA passes, release artefact verification, branch protection,
    post-release.

  docs/operator/performance-baselines.md (NEW, ~100 lines):
    From testing-guide.md "Part 39: Performance Spot Checks". Four
    operator-runnable benchmarks (API request handling, inventory list
    pagination, scheduler tick, bulk revoke) with baseline numbers and
    when-to-re-baseline guidance.

  docs/operator/helm-deployment.md (NEW, ~120 lines):
    From testing-guide.md "Part 52: Helm Chart Deployment". Operator
    runbook for the bundled deploy/helm/certctl/ chart: prereqs,
    install, four cert-source patterns, verify, upgrade, troubleshooting.

  docs/reference/cli.md (NEW, ~120 lines):
    From testing-guide.md "Part 28: CLI Tool". certctl-cli command
    reference with command-group breakdown, common workflows
    (list/filter, renew, revoke, bulk import, EST enrollment, status),
    output formats, CI/CD integration patterns.

docs/README.md navigation index updated to include the 6 new docs:
  Reference section gains: cli.md, release-verification.md (was added
    in Phase 13)
  Operator section gains: helm-deployment.md, performance-baselines.md
  Contributor section gains: qa-prerequisites.md, gui-qa-checklist.md,
    release-sign-off.md

docs/testing-guide.md deleted. Git history preserves the 8268 lines —
if any specific test case is found missing from inline test code or
the destination docs during future work, lift from `git show
HEAD~1:docs/testing-guide.md`.

Net: docs/ total line count drops by ~7700 lines (28%), from 26,369
to 18,742. testing-guide.md was the single largest doc; pruning it is
the single biggest content-edit win of the entire restructure.

Phase 5 is the last major content phase. Remaining: Phase 4 follow-on
(per-connector page extractions from reference/connectors/index.md),
Phase 15 (WHAT/HOW/WHY remediation), Phase 16 (final acceptance gate).
This commit is contained in:
shankar0123
2026-05-05 03:38:54 +00:00
parent fd4eb3b165
commit b452013dd9
8 changed files with 641 additions and 8268 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/contributor/gui-qa-checklist.md
+68
View File
@@ -0,0 +1,68 @@
# GUI QA Checklist
> Last reviewed: 2026-05-05
Manual GUI verification pass for release sign-off. Vitest covers component-level behavior; this checklist covers end-to-end flows that only land correctly when the React SPA, the REST API, and the database are all wired together.
## Prereqs
The full stack must be running and healthy per [`qa-prerequisites.md`](qa-prerequisites.md). Open `https://localhost:8443` in a fresh browser session (Incognito / Private mode is fine — avoids cached state from previous QA passes).
## Pages to verify
For each page, the verification is "open it, confirm it renders without console errors, exercise the documented action, confirm the action lands as expected."
| Page | Action to verify | Expected result |
|---|---|---|
| `/dashboard` | Page loads, all 4 stat cards populate | Total / Active / Expiring / Expired counts match `GET /api/v1/stats/summary` |
| `/certificates` | Inventory list paginates | "Next page" button works; URL updates with cursor; row count consistent |
| `/certificates/<id>` | Detail page opens for any cert | Cert chain renders, deployment status shows, audit timeline visible |
| `/issuers` | Catalog renders all configured issuers | Each issuer card shows last-used / status; clicking opens detail |
| `/issuers/<id>` | Issuer config form | Edit + Save round-trips through `PATCH /api/v1/issuers/<id>` |
| `/issuers/hierarchy` | CA tree view | Multi-level hierarchy renders; admin-gated CRUD buttons present for admins only |
| `/agents` | Fleet view | Online/offline status accurate; OS/arch grouping correct |
| `/agents/<id>` | Agent detail | Last heartbeat, registered date, deployment job history |
| `/agents/groups` | Agent groups CRUD | Create + edit + delete a test group; verify dynamic membership matching |
| `/jobs` | Job queue | Filter by status / type works; click into a job opens detail |
| `/jobs/<id>` | Job detail | Status, retries, logs, owner attribution |
| `/policies` | Renewal policies CRUD | Edit AlertChannels matrix, save, verify backend reflects change |
| `/profiles` | Certificate profiles | EKU constraints + max TTL editable; profile binding works |
| `/notifications` | Notifier config | Test connection button against each configured notifier |
| `/discovery` | Discovery triage | Claim / Dismiss buttons round-trip to backend |
| `/network-scans` | Scan target CRUD | Create scan target, trigger immediate scan, results appear |
| `/audit` | Audit trail | Filter by actor / action / time range; CSV export works |
| `/short-lived` | Short-lived credential dashboard | Live TTL countdown updates; auto-refresh every 10s |
| `/observability` | Observability dashboard | Charts render: expiration heatmap, renewal trends, issuance rate |
| `/health` | Health monitor | TLS endpoint health: healthy / degraded / down states accurate |
| `/digest` | Digest preview | Email preview renders; "Send digest" button dispatches |
| `/owners` | Owners CRUD | Create owner with team, edit, delete (after reassigning certs) |
| `/teams` | Teams CRUD | Create + delete; verify cascade removes orphan owners |
| `/scep` | SCEP admin tabs | Profiles / Intune Monitoring / Recent Activity all populate |
| `/est` | EST admin tabs | Profiles / Recent Activity / Trust Bundle all populate |
| `/login` | Login flow | API key entry persists for the session; bad key rejected |
## Console hygiene
Open browser DevTools and confirm:
- No uncaught exceptions on any page
- No 404 / 500 responses in the Network tab from API calls
- No CORS errors
- No CSP violations
## Mobile / narrow-viewport
The dashboard is desktop-first but should not break catastrophically on narrow viewports. Resize the browser to 380px width; confirm:
- Sidebar collapses to a hamburger menu
- Tables either scroll horizontally or stack on mobile
- Forms remain usable
## Accessibility spot-check
- Tab through any single page using only the keyboard. Every interactive element must be reachable, and the focus indicator must be visible.
- Lighthouse accessibility audit on `/dashboard`: target ≥ 90.
## Sign-off
Document any deviations in the release sign-off matrix at [`release-sign-off.md`](release-sign-off.md).
docs/contributor/qa-prerequisites.md
+99
View File
@@ -0,0 +1,99 @@
# QA Prerequisites
> Last reviewed: 2026-05-05
Operational prereqs for running release QA against certctl. Before any of the contributor-facing testing surfaces (test-environment.md, gui-qa-checklist.md, release-sign-off.md) are useful, the local stack needs to be in a known-good state.
## Why manual QA on top of automated tests?
Automated tests mock dependencies and run in isolation. Manual QA validates the full integrated stack: real PostgreSQL, real HTTP, real agent binary, real file I/O, real scheduler timing. It catches issues that unit tests can't: migration ordering, Docker networking, env var parsing, browser rendering, and timing-dependent scheduler behavior.
## Environment setup
**Step 1: Start the full stack.**
```bash
cd deploy && docker compose -f docker-compose.demo.yml up --build -d
```
This builds three containers (postgres, certctl-server, certctl-agent) and runs them on a bridge network. The `--build` flag ensures you're testing the current code, not a stale image. The `demo` overlay seeds the database with realistic fixtures.
**Step 2: Wait for healthy state.**
```bash
for i in $(seq 1 30); do
STATUS=$(docker compose ps --format json 2>/dev/null | jq -r 'select(.Health != null) | "\(.Name): \(.Health)"' 2>/dev/null)
echo "$STATUS"
echo "$STATUS" | grep -q "unhealthy\|starting" || break
sleep 2
done
```
Why: Docker Compose starts containers in dependency order (postgres → server → agent), but "started" doesn't mean "ready." Health checks confirm postgres accepts connections, the server responds on `/health`, and the agent process is running.
**Step 3: Set shell variables used throughout the QA flow.**
```bash
export SERVER=https://localhost:8443
export API_KEY="change-me-in-production"
export AUTH="Authorization: Bearer $API_KEY"
export CT="Content-Type: application/json"
export CACERT="--cacert ./deploy/test/certs/ca.crt"
```
Every curl command in QA docs uses these variables. Setting them once avoids typos and keeps the docs copy-pasteable.
> **Note:** The default Docker Compose sets `CERTCTL_AUTH_TYPE: none` for the demo overlay, meaning auth is disabled. Tests that exercise auth require flipping this to `api-key`; instructions are in the relevant test docs.
**Step 4: Build CLI and MCP server binaries on the host.**
```bash
go build -o certctl-cli ./cmd/cli/...
go build -o certctl-mcp ./cmd/mcp-server/...
```
The CLI and MCP server are separate binaries that talk to the server over HTTP. Building them verifies the code compiles and produces the executables you'll test later.
## Demo data baseline
The seed data (`migrations/seed.sql` + `migrations/seed_demo.sql`) pre-populates the database with realistic fixtures. Confirm it loaded:
```bash
curl -s $CACERT -H "$AUTH" $SERVER/api/v1/stats/summary | jq .
```
**Expected shape:**
```json
{
"total_certificates": 15,
"active_certificates": ...,
"expiring_certificates": ...,
"expired_certificates": ...,
"pending_renewals": ...
}
```
**Reference IDs in the demo data** (used across QA docs):
| Resource | IDs | Count |
|---|---|---|
| Teams | `t-platform`, `t-security`, `t-payments`, `t-frontend`, `t-data` | 5 |
| Owners | `o-alice`, `o-bob`, `o-carol`, `o-dave`, `o-eve` | 5 |
| Policies | `rp-standard`, `rp-urgent`, `rp-manual` | 3 |
| Issuers | `iss-local`, `iss-acme-le`, `iss-stepca`, `iss-digicert` | 4 |
| Agents | `ag-web-prod`, `ag-web-staging`, `ag-lb-prod`, `ag-iis-prod`, `ag-data-prod` | 5 |
| Targets | `tgt-nginx-prod`, `tgt-nginx-staging`, `tgt-f5-prod`, `tgt-iis-prod`, `tgt-nginx-data` | 5 |
| Profiles | `prof-standard-tls`, `prof-internal-mtls`, `prof-short-lived`, `prof-high-security` | 4 |
| Certificates | `mc-api-prod`, `mc-web-prod`, `mc-pay-prod`, etc. | 15 |
| Agent Groups | `ag-linux-prod`, `ag-linux-amd64`, `ag-windows`, `ag-datacenter-a`, `ag-manual` | 5 |
| Network Scan Targets | `nst-dc1-web`, `nst-dc2-apps`, `nst-dmz` | 3 |
## Once these are green
Move to the appropriate downstream surface:
- [`test-environment.md`](test-environment.md) — full local environment tutorial with real CAs (Pebble, step-ca, etc.)
- [`gui-qa-checklist.md`](gui-qa-checklist.md) — manual GUI test pass
- [`release-sign-off.md`](release-sign-off.md) — release-day checklist
- [`testing-strategy.md`](testing-strategy.md) — what we test in CI vs daily deep-scan vs manual QA
docs/contributor/release-sign-off.md
+93
View File
@@ -0,0 +1,93 @@
# Release Sign-Off
> Last reviewed: 2026-05-05
Release-day checklist for tagging a new certctl release. Walks through the gates that must be green before pushing the tag, in the order they should be verified.
## Pre-release: code state
| Gate | How to check | Pass |
|---|---|---|
| `master` is at the commit you intend to tag | `git log -1 --format='%H %s'` | ☐ |
| Working tree clean | `git status -sb` | ☐ |
| Local matches GitHub | `curl -sS https://api.github.com/repos/certctl-io/certctl/commits/master \| grep -oE '"sha": "[a-f0-9]+"' \| head -1` matches local | ☐ |
| `WORKSPACE-CHANGELOG.md` updated with the release's milestones | manual review | ☐ |
| `certctl/CHANGELOG.md` updated (release-facing) | manual review | ☐ |
| Migration ladder ends cleanly | `ls migrations/*.up.sql \| sort \| tail -3` shows the right last migration | ☐ |
## Pre-release: automated gates (CI)
| Gate | How to check | Pass |
|---|---|---|
| CI pipeline green on the tag-target commit | GitHub Actions web UI | ☐ |
| `make verify` clean locally | run from repo root | ☐ |
| `go test -race -count=1 ./...` clean | full race check | ☐ |
| `golangci-lint run ./...` clean | local lint | ☐ |
| `govulncheck ./...` clean | vulnerability scan | ☐ |
| Coverage thresholds met (service ≥55%, handler ≥60%, domain ≥40%, middleware ≥30%) | `go test -coverprofile=cover.out ./... && go tool cover -func=cover.out` | ☐ |
| Frontend type-check + Vitest + Vite build clean | `cd web && npm run typecheck && npm run test && npm run build` | ☐ |
## Pre-release: manual QA passes
| Surface | Checklist | Pass |
|---|---|---|
| Local stack boots clean from scratch | `qa-prerequisites.md` Steps 1-4 green | ☐ |
| GUI QA checklist | `gui-qa-checklist.md` end to end | ☐ |
| End-to-end test environment | `test-environment.md` Steps 1-14 green | ☐ |
| Performance baselines | `performance-baselines.md` four spot checks within bounds | ☐ |
| Helm chart deploys clean | `helm-deployment.md` install + verify | ☐ |
| ACME server interop (cert-manager) | `make acme-cert-manager-test` green | ☐ |
| ACME server RFC conformance (lego) | `make acme-rfc-conformance-test` green | ☐ |
## Release artefact verification
After the release workflow runs (triggered by tag push), verify the published artefacts:
| Artefact | How to verify | Pass |
|---|---|---|
| Cosign keyless OIDC signature on `checksums.txt` | per `docs/reference/release-verification.md` step 2 | ☐ |
| SLSA Level 3 provenance on each binary | step 3 | ☐ |
| Container image signature + SBOM + provenance | step 4 | ☐ |
| Release notes published on GitHub Releases page | manual review | ☐ |
| ghcr.io images at `ghcr.io/certctl-io/certctl-{server,agent}:<tag>` pullable | `docker pull` round-trips | ☐ |
## Branch protection + tag push
| Gate | How to check | Pass |
|---|---|---|
| `master` branch protection rule allows the tag push | Repository Settings → Branches | ☐ |
| Tag pushed | `git tag -s v<version> -m 'Release v<version>'; git push origin v<version>` | ☐ |
| Release workflow kicked off in GitHub Actions | watch the Actions tab | ☐ |
## Post-release
| Gate | How to check | Pass |
|---|---|---|
| Release workflow completed without errors | GitHub Actions | ☐ |
| Sample binary downloaded and Cosign-verified by an operator who is not the release author | another team member | ☐ |
| `WORKSPACE-CHANGELOG.md` notes the tag commit SHA | manual edit | ☐ |
| `cowork/CLAUDE.md` "Active Focus" → "Current tag" updated | manual edit | ☐ |
| `certctl.io/index.html` star count + `data-gh-version` rendering picks up the new tag | open the landing page in 6+ hours (cache TTL) | ☐ |
| Reddit / Hacker News / LinkedIn announcement drafted (if a major release) | per the operator's promotion playbook | ☐ |
## If a gate fails
Revert the tag push immediately:
```bash
git push --delete origin v<version>
git tag -d v<version>
```
Investigate, fix, re-tag.
## Related docs
- [`docs/contributor/qa-prerequisites.md`](qa-prerequisites.md) — local stack prereqs
- [`docs/contributor/test-environment.md`](test-environment.md) — full local environment tutorial
- [`docs/contributor/gui-qa-checklist.md`](gui-qa-checklist.md) — GUI manual QA pass
- [`docs/contributor/testing-strategy.md`](testing-strategy.md) — what we test in CI vs deep-scan vs manual QA
- [`docs/contributor/ci-pipeline.md`](ci-pipeline.md) — CI shape and regression guards
- [`docs/operator/performance-baselines.md`](../operator/performance-baselines.md) — performance regression spot checks
- [`docs/operator/helm-deployment.md`](../operator/helm-deployment.md) — Helm install + verify
- [`docs/reference/release-verification.md`](../reference/release-verification.md) — Cosign / SLSA / SBOM verification procedure