Lesson 7 / الدرس 7

Collections, variables and secrets / المجموعات والمتغيرات والأسرار

The same twelve requests have to run against your machine, the test server and staging, without anyone editing twelve URLs — and without a real password ever being written into a file that gets shared.

الطلبات الاثنا عشر نفسها يجب أن تجري على جهازك وعلى خادم الاختبار وعلى بيئة التجهيز، دون أن يحرّر أحد اثني عشر رابطًا — ودون أن تُكتب كلمة مرور حقيقية قط في ملف يُشارَك.

The first API test you save has the server address typed into it. So does the second. By the twelfth, moving from your machine to the test server is a find-and-replace, and one of the twelve will be missed — usually the one that deletes something. A variable is not a convenience here; it is what makes the set of requests a single thing that can be pointed somewhere.

Three layers, and what belongs in each

Layer	Holds	Shared?
Collection	The requests themselves, and variable NAMES	Yes — committed to git
Environment	The values: base URL, test account, ids	Usually yes, when they are not secret
Secrets	Tokens, passwords, API keys	Never — local only, or from a vault

The collection says {{baseUrl}}/orders; the environment says what baseUrl is today; the secret lives somewhere neither of them can be committed with.

المجموعة تقول {{baseUrl}}/orders؛ والبيئة تقول ما هو baseUrl اليوم؛ والسر يعيش في مكان لا يمكن إيداع أيٍّ منهما معه.

// Committed: names only, no values.
//   POST {{baseUrl}}/sign-in
//   Authorization: Bearer {{token}}

// Environment 'local'      baseUrl = http://localhost:8000
// Environment 'test'       baseUrl = https://test.example.com
// Environment 'staging'    baseUrl = https://staging.example.com

// token is never typed anywhere. It is captured from the sign-in response
// and lives only in memory for this run:
const res = await fetch(`${baseUrl}/sign-in`, { /* ... */ });
const { token } = await res.json();
// ...then passed to every later request in the run.

Switching environment now points twelve requests at a different server with one click, and the token is never written down at all — it is fetched at the start of every run, which is also why an expired token stops being a recurring mystery.

Environments differ in ways that matter

A test passing on staging and failing on test is often not a bug at all — it is different data, a different configuration, or a feature switched on in one and off in the other. Always say which environment a result came from, in the bug report and in the test output. "It fails" and "it fails on staging only" send a developer to two entirely different places.

Check yourself / اختبر نفسك

1. What belongs in the collection rather than the environment?

2. A test passes on staging and fails on the test server. What is the first thing to suspect?

3. Why capture the token from a sign-in response rather than typing it into a variable?