v1.0 RC Test Plan

Plystra v1.0 RC Test Plan

Document Status

Field	Value
Product	Plystra
Version	v0.0.1
Document Type	Release Candidate test plan
Scope	Stable Self-Hosted Core
Status	RC execution plan

1. Purpose

This document defines the test plan for Plystra v1.0 Release Candidate.

The purpose is to validate that the v1.0 Core can be installed, migrated, run, tested, and used from a clean environment.

The test plan focuses on:

clean clone usability
Docker self-hosted baseline
migration correctness
Ent drift correctness
authorization correctness
audit correctness
Resource Registry correctness
Core CRUD API correctness
OpenAPI correctness
request ID canonical envelope
release documentation correctness
Bearer user session protection for sensitive APIs
disabled-by-default data and metrics surfaces

This test plan should be executed before tagging:

v0.0.1

It should be executed again before final:

v1.0.0

2. Test Environment Matrix

Run tests against at least the following environments.

2.1 Local Development Environment

Component	Requirement
OS	macOS or Linux
Go	Project-supported version
Docker	Installed
Docker Compose	Installed
PostgreSQL	Via Docker Compose
Network	Localhost

2.2 Clean Linux Environment

Component	Requirement
OS	Ubuntu LTS recommended
Go	Project-supported version
Docker	Installed
Docker Compose	Installed
PostgreSQL	Via Docker Compose
State	Clean clone, no local cache assumption

2.3 CI Environment

Component	Requirement
Go tests	Required
PostgreSQL integration tests	Required
Migration apply tests	Required
Ent check	Required
OpenAPI check	Recommended
Smoke tests	Recommended

3. Required Test Data

The RC must include Finance Reviewer demo data.

Users

user_alice
user_bob

Space

space_acme

Groups

finance
finance.apac
finance.emea
legal
legal.emea

Members

member_finance_reviewer
member_invoice_creator

UserMembers

um_alice_finance_reviewer active delegate
um_bob_finance_reviewer active login
um_alice_finance_reviewer_revoked revoked delegate

Role

finance_approver

Permission

invoice:approve:group_tree

Resources

invoice_001 under finance.apac
invoice_002 under legal.emea

4. Test Execution Overview

Execute the RC test plan in this order:

1. Clean clone test
2. Environment configuration test
3. Docker Compose startup test
4. Migration test
5. Ent drift test
6. Doctor test
7. Unit test suite
8. PostgreSQL integration test suite
9. Health endpoint smoke test
10. Authz smoke test
11. Resource Registry smoke test
12. Core CRUD smoke test
13. AuditLog smoke test
14. OpenAPI verification
15. request ID canonical envelope verification
16. Production safety verification
17. Documentation verification
18. RC sign-off

5. Clean Clone Test

Objective

Prove that a developer can start from a clean clone and follow README instructions.

Steps

git clone https://github.com/plystra/plystra.git
cd plystra
cp .env.example .env

Then follow the README exactly.

Expected Results

Repository clones successfully.
.env.example is present.
README instructions are accurate.
No undocumented secrets are required.
No local maintainer-only files are required.

Failure Conditions

README references missing commands.
README references missing files.
Startup requires undocumented environment variables.
Demo requires local state not included in repository.

6. Docker Compose Startup Test

Objective

Prove the self-hosted baseline works.

Steps

docker compose down -v
docker compose up -d
docker compose ps
docker compose logs --tail=100

Expected Results

PostgreSQL starts.
Plystra Core starts if compose includes the service.
Containers remain running.
Logs do not contain fatal startup errors.
Database settings match .env.example.

Additional Checks

docker compose restart
docker compose ps

Expected:

Restart works.
Data volume remains intact.
Core reconnects to PostgreSQL.

7. Migration Test

Objective

Prove migrations apply cleanly.

Empty Database Steps

docker compose down -v
docker compose up -d postgres
plystractl migrate up
plystractl migrate verify

Expected Results

All migrations apply.
Migration status is recorded.
Migration verification passes.
Schema is ready for Core.

Upgrade Database Steps

If previous release schema is available:

# Restore or initialize previous release schema
plystractl migrate up
plystractl migrate verify

Expected:

Existing schema upgrades successfully.
No destructive migration runs without explicit approval.
Core starts after upgrade.

Failure Conditions

Migration applies only on the maintainer’s database.
Migration fails on empty DB.
Migration fails from previous release.
Migration verification reports drift.

8. Ent Drift Test

Objective

Prove Ent schema, generated code, and migrations are synchronized.

Steps

plystractl ent check

If project uses codegen check:

go generate ./ent
git diff --exit-code

Expected Results

Ent drift is zero.
Generated code is up to date.
Migrations match Ent schema.

Failure Conditions

Generated code changes after go generate.
Migration diff appears after schema check.
plystractl ent check reports drift.

9. Doctor Test

Objective

Prove operational diagnostics work.

Steps

plystractl doctor

Expected Results

Doctor reports:

configuration status
database connectivity
migration status
schema readiness
environment mode
service readiness

Failure Conditions

Doctor passes when database is unreachable.
Doctor passes with invalid schema.
Doctor output lacks actionable error messages.

10. Unit Test Suite

Objective

Prove core logic correctness.

Steps

go test ./...

Required Coverage Areas

scope resolver
deny code mapping
trace builder
same-space validation
UserMember status validation
UserMember expiration validation
group_tree path matching
union semantics
AuditLog snapshot builder
request envelope formatting

Expected Results

All unit tests pass.
No flaky tests.
No tests require external services unless marked integration.

11. PostgreSQL Integration Test Suite

Objective

Prove Core works with real PostgreSQL.

Steps

PLYSTRA_DATABASE_URL=postgres://... go test ./...

or project-specific integration command.

Required Coverage Areas

migrations
Ent store
LoadAuthorizationContext
authz/check against database
authz/explain against database
AuditLog writes
Resource Registry registration
CRUD APIs
same-space constraints
revoked UserMember
expired UserMember

Expected Results

Tests pass against PostgreSQL.
Tests do not depend on local leftover state.
Tests clean up after themselves or use isolated DB.

12. Health Endpoint Smoke Test

Objective

Prove operational endpoints work.

Steps

curl -s http://localhost:8080/api/v1/health
curl -s http://localhost:8080/api/v1/ready
curl -s http://localhost:8080/api/v1/version

Canonical operational routes:

curl -s http://localhost:8080/api/v1/health
curl -s http://localhost:8080/api/v1/ready
curl -s http://localhost:8080/api/v1/version

Expected Results

/health returns service health.
/ready checks database and migration readiness.
/version returns version and schema information.
Legacy paths remain compatible if promised.

13. Authorization Smoke Test

Objective

Prove authz/check and authz/explain work.

Required Cases

Case 1: Allow Finance/APAC

Expected:

decision = allow
deny_code = null

Case 2: Deny Legal/EMEA

Expected:

decision = deny
deny_code = SCOPE_OUT_OF_BOUNDS

Case 3: Bob Shared Member Allow

Expected:

decision = allow
actor_user_id = user_bob
actor_member_id = member_finance_reviewer

Case 4: Revoked UserMember Deny

Expected:

decision = deny
deny_code = USER_MEMBER_REVOKED

Explain Trace Checks

For each case, verify:

trace_version exists
actor snapshot exists
space snapshot exists
target resource snapshot exists
matched_candidates exists
scope_check exists
reason exists
audit context exists if audit is written

14. Resource Registry Smoke Test

Objective

Prove newly registered Resources can enter the authorization chain.

Steps

Register a new Resource type or Resource record.
Attach it to a Space.
Attach it to a Group if scope requires it.
Attach owner Member if self scope requires it.
Create or reuse Permission.
Create RolePermission.
Create MemberRole.
Call authz/check.

Expected Results

Resource is created.
Resource is queryable.
Resource passes same-space validation.
Resource can be used by authz/check.
Resource can be used by authz/explain.
Resource operations are auditable.

15. Core CRUD Smoke Test

Objective

Prove all major Core APIs work.

Entities

Run create/read/list/update/status workflow for:

Users
Spaces
Groups
Members
UserMembers
Roles
Permissions
MemberRoles
RolePermissions
Resources

Run read/list/filter workflow for:

AuditLogs

Required Workflow Verifications

disable
restore
revoke
archive
validation error
same-space rejection
not found
request ID in response

Expected Results

All major CRUD APIs return expected status codes.
All validation errors use standard envelope.
AuditLog does not expose update/delete.
Generated Ent internals are not leaked.

16. AuditLog Smoke Test

Objective

Prove AuditLog correctness.

Steps

Run allow authz check.
Run deny authz check.
Query AuditLogs by decision.
Query AuditLogs by deny code.
Query AuditLogs by actor.
Query AuditLogs by resource.
Query AuditLogs by request ID.
Inspect trace snapshot.

Expected Results

Allow decision is logged.
Deny decision is logged.
Trace contains snapshots, not only IDs.
Trace includes matched candidates.
Trace includes deny code for deny decisions.
AuditLog update is unavailable or rejected.
AuditLog delete is unavailable or rejected.

17. OpenAPI Verification

Objective

Prove API docs match implementation.

Required

All routes implemented in v1.0 are documented.
All documented routes exist.
Request schemas match accepted payloads.
Response schemas match actual responses.
Error envelope is documented.
Canonical top-level request_id behavior is documented.
Deny codes are documented or referenced.
Authz trace schema is documented.

Optional Automated Checks

Generate client from OpenAPI.
Run basic generated client smoke test.
Compare route registry against OpenAPI paths.

18. Request ID Verification

Objective

Prove every API response carries one canonical top-level request ID.

Required

Responses should include:

{
  "request_id": "req_..."
}

Checks

Top-level request_id exists.
meta.request_id is not returned.
OpenAPI documents the top-level field only.
Structured logs and AuditLog records can be correlated through the same request ID.

19. Production Safety Verification

Objective

Prove production mode blocks unsafe Ent auto apply behavior.

Steps

Run production mode command that would apply Ent schema automatically.

Expected Result

Command is rejected.
Error message explains why.
Error message directs user to versioned migrations.
Documentation explains the behavior.

Acceptance Rule

Production must not silently mutate schema through Ent auto migration.

20. Documentation Verification

Objective

Prove users can operate v1.0 from public docs.

Required Docs To Check

README
Quickstart
v1.0 readiness checklist
v1.0 RC test plan
v1.0 release notes
request ID canonical envelope
migration and upgrade guide
OpenAPI v1.0
Ent integration guideline

Checks

Commands are accurate.
File paths are accurate.
Environment variables are accurate.
Non-goals are clear.
Optional components are clearly marked optional.
v1.0 blocking scope is clear.
Production migration behavior is documented.
request ID canonical envelope is documented.

21. RC Sign-off Template

Before tagging, fill this out.

Area	Result	Notes
Clean clone
Docker Compose
Migration empty DB
Migration upgrade DB
Ent drift
Doctor
Unit tests
PostgreSQL integration tests
Health endpoints
Authz check/explain
Resource Registry
CRUD smoke tests
AuditLog
OpenAPI
request ID canonical envelope
Production safety
Docs

22. Final RC Decision

Tag v0.0.1 only if:

all blocking tests pass
all release docs are committed
OpenAPI matches implementation
no known migration blocker exists
no known authz correctness blocker exists
no known AuditLog correctness blocker exists
no known clean install blocker exists

If any blocker remains, do not tag RC.