Phase 1: Foundation and auth Test

[jenniferoko]

Phase 1 — Foundation and Authentication

Overview

Jennifer's Deliverable

Before implementation begins, Jennifer will:

• Confirm the shared design patterns are understood.
• Walk the engineer through the API envelope contract.
• Explain the purpose of each shared helper.
• Review and approve the shared support layer before any test specifications are written.

---

Engineer Deliverables

Implement the shared testing framework:

support/
├── client.ts         # Typed HTTP wrapper
├── assertions.ts     # Envelope and array helpers
├── cleanup.ts        # Resource cleanup registry
└── fixtures.ts       # Authenticated Playwright fixture

playwright.config.ts

tests/
├── 01-auth.spec.ts       # Tests 1–5
└── 02-discovery.spec.ts  # Tests 6–10

---

Phase Gate

Phase 1 is complete only when:

• ✅ All 10 tests pass
• ✅ Jennifer reviews the envelope assertion helpers
• ✅ Cleanup registry implementation is approved
• ✅ Test tagging strategy is verified

Only then may Phase 2 begin.

---

Shared Design Patterns

Why a Typed Client Wrapper?

Every API test performs the same basic operations:

• Build the request URL
• Attach authentication headers
• Send the request
• Verify HTTP status
• Parse JSON

Without a wrapper, every test repeats this plumbing.

Preferred

const env = await client.get<VM[]>('/virtual-machines');

assertArray(env);

Instead of

const res = await request.get(
  `${BASE}/virtual-machines`,
  {
    headers: {
      Authorization: `Bearer ${TOKEN}`
    }
  }
);

const env = await res.json();

expect(res.status()).toBe(200);
expect(env.status).toBe('Success');
expect(Array.isArray(env.data)).toBe(true);

Benefits

• Cleaner tests
• Less duplication
• Strong typing
• Easier maintenance
• Consistent error handling

The wrapper keeps tests focused on behaviour, not HTTP plumbing.

---

Why a Cleanup Registry?

Tests frequently create temporary resources.

If a test fails halfway through execution, those resources must still be removed.

The cleanup registry records every created resource and automatically deletes them during afterAll(), regardless of whether the test passed or failed.

Example

// During the test

const vm = await client.post(
  '/virtual-machines',
  payload
);

cleanup.register(
  `/virtual-machines/${vm.data.slug}`
);

// Automatically executed in afterAll()

await cleanup.run(client);

Benefits

• No orphaned resources
• Cleaner environments
• Safer reruns
• Independent cleanup logic

---

Why Test Tags?

Different execution scenarios require different subsets of tests.

Scenario	Tests	Runtime
Pull Request	@critical	~10 seconds
Manual Service Validation	@compute, @storage, etc.	~5 minutes
Nightly Regression	@smoke	~20 minutes

Jennifer defines which tags belong on each test.

The engineer applies the tags during implementation.

---

Phase 1 Test Specifications

File

tests/01-auth.spec.ts

Tag

@critical

Test #	Test Name	Method	Endpoint	Pass Condition
1	Valid token is accepted	GET	/regions	HTTP 200, status = Success
2	Missing token is rejected	GET	/regions	HTTP 401, status = Error
3	Malformed token is rejected	GET	/regions	HTTP 401, status = Error
4	Response envelope contains required fields	GET	/regions	status, message, timezone, and data are present
5	Token authorizes compute endpoints	GET	/virtual-machines	HTTP 200, status = Success

---

Why These Tests Matter

Tests 1–3 verify authentication.

Failures indicate:

• Invalid credentials
• Revoked token
• Authentication service outage

Test 4 validates the API response contract.

If this test fails, the response structure has changed and downstream tests may produce misleading results.

Test 5 confirms that authenticated requests can access compute resources.

---

Execution Policy

The authentication suite (Tests 1–5) executes on every deployment before any additional smoke tests.

This provides rapid feedback and prevents downstream failures caused by authentication or API contract issues.

---

Phase 1 Acceptance Criteria

• Shared support layer implemented
• client.ts completed
• assertions.ts completed
• cleanup.ts completed
• fixtures.ts completed
• playwright.config.ts configured
• 01-auth.spec.ts implemented
• 02-discovery.spec.ts implemented
• All 10 tests passing
• Envelope assertions used consistently
• Cleanup registry verified
• Test tags applied correctly
• Jennifer reviews and signs off before Phase 2