Minimal Postman smoke set

1. Smoke set: purpose and size

A smoke set sounds like something about fire safety, and, honestly, that is a very accurate metaphor. It is not full testing, not “cover everything,” and not “check every edge.” A smoke set is a quick ritual: a few requests that answer one question: “Is the basic scenario still working, or is something already burning and smelling like overheated wiring?”

When you work with an external API, especially in a training course, where you do not control the provider, there is always a risk that something changes: a field is renamed, the path changes, the service starts returning a different status, or it is simply temporarily down. If your collection has 60 requests, half of which are named “test2-final-final-really,” then when a problem appears, you will be doing archaeology instead of diagnostics.

That is exactly why the smoke set must be short. Its value is not in the number of scenarios, but in the fact that you can run it often and without internal resistance. If the check takes two minutes, you run it before changing something, after changing it, and whenever “something seems odd.” If the check takes half an hour, you will... well, you know: “I’ll do it tomorrow” is the official status for “never.”

In the context of our ReadLater Starter project, the smoke set is the minimal “entry map” into the external catalog contract. It exists so that at any moment you can confirm that search works, details by the found identifier work, and at least a couple of negative boundaries behave predictably. This will be your anchor when you stop looking at the API through the Postman UI and start treating it as an agreement that your code relies on.

2. Required catalog scenarios for the project

If we put aside romance and speak practically, ReadLater Starter in the client phase does two things: it searches for a book and retrieves its details. Everything else is “maybe someday,” and a smoke set is not the place for “someday.” It is the place for “must.”

To avoid spreading out too much, it is useful to fix a minimal matrix in advance: which requests we keep, which variables they use, and what result we consider normal. Below is a good smoke-set “skeleton” for our catalog in neutral terms, without tying it to a specific provider.

Notice one subtle thing: in our case, the smoke set checks not “data correctness” (that the book is really “Clean Code”), but “contract liveliness.” We are not examining the catalog, we are checking that we have not lost our understanding of its shape. This is an important mindset adjustment: in an API contract, the main character is the structure and semantics of the response, not the specific values of a particular record.

3. Collection layout: structure and order

A Postman collection is not just a folder where requests live. In normal life, it is part documentation, part reproducibility, and part your future peace of mind. So now we are doing a small but important thing: turning a “set of requests” into a “readable story.”

The simplest and most workable format is to create one folder inside the collection called Catalog (smoke) and then arrange the requests so that the scenario and order are visible at a glance. Order matters not because it is pretty, but because we have a chained flow: Details depends on Search, which saves bookId. If you accidentally send Details first, you get an error that does not say anything about the catalog problem, it says something about your discipline.

Here is an example structure that is easy to read and needs almost no explanation:

ReadLater / External Catalog
└─ Catalog (smoke)
   ├─ 01 - Search - happy-path
   ├─ 02 - Details - happy-path (uses {{bookId}})
   ├─ 03 - Search - negative - empty query
   └─ 04 - Details - negative - missing id (uses {{missingBookId}})

Yes, the prefixes 01, 02 are a bit old-school. But they work even when Postman decides to sort requests alphabetically and you open the collection a week later “after work, without coffee, but with a problem.” This is one of those cases where a small formality saves a lot of nerves.

Another practical touch is the labels. In each request’s Description field in Postman, it is worth writing one or two phrases: what is being checked and what is expected. Not a novel, just a cheat sheet for your future self. Future you will thank you for it. Sometimes even out loud.

4. Environment variables and portability

A smoke set does not need a whole zoo of variables. It needs one specific inventory so that happy-path and negative-path run equally predictably: baseUrl, searchQuery, limit, bookId, missingBookId.

Here is what the environment may look like:

{
  "baseUrl": "https://catalog.example.com",
  "searchQuery": "clean code",
  "limit": "3",
  "bookId": "",
  "missingBookId": "DOES_NOT_EXIST"
}

bookId is the working variable of the happy-path chain: Search fills it, and Details picks it up. missingBookId is set manually once and is only needed for a stable not-found scenario. The rule for baseUrl stays the same: no trailing /, so that URL templates do not break when concatenated.

If a second test environment appears, create a second environment with the same variable names instead of a new dictionary. Then the smoke set switches with one click instead of manual replacement of half the collection.

5. Happy-path: Search → bookId → Details

The most “alive” part of the smoke set is the linked happy-path. But here we do not need another full breakdown of the Tests script. For the final assembly, one thing matters: 01 - Search - happy-path must leave a fresh bookId behind, and when the result is empty it must not quietly carry over the value from the previous run. Then 02 - Details - happy-path really checks the second step of the contract, not a random old ID.

The URL of the second step stays simple:

{{baseUrl}}/books/{{bookId}}

If Details suddenly stops working, the first thing to check is not only the endpoint itself, but also what exactly Search saved. In a chained smoke flow, that is just as much a part of diagnosis as the status code.

flowchart LR
  A["01 Search (happy)"] -->|Tests: set bookId| B[(Environment)]
  B --> C["02 Details (happy)"]

6. Negative path: the two most useful requests

Negative-path in a smoke set is not there to “torment the API.” It exists to reveal the boundaries of the contract. An external catalog almost always has two types of negative situations that are useful to understand: bad/empty input in search and a details request for a non-existent resource.

In the 03 - Search - negative - empty query request, we intentionally send an empty query. Important: this is not about “breaking the internet,” it is about checking contract behavior. Sometimes the service returns 400 Bad Request, sometimes 200 OK with an empty list, and sometimes “anything at all.” Any of these options may be acceptable if it is stable and you have documented it.

{{baseUrl}}/search?q=

In the 04 - Details - negative - missing id request, it is better to use not a string typed in by hand, but the missingBookId variable. Then the not-found scenario remains as reproducible as happy-path: the meaning lives in the variable name, not in random URL text.

{{baseUrl}}/books/{{missingBookId}}

Why are these two requests so useful? Because they help distinguish “the contract is designed this way” from “the service is broken.” If you suddenly get a strange response on happy-path, you can quickly look at the negative-path. If the negative-path also became strange (for example, instead of a predictable 404 you get a 500), the problem is most likely on the provider side or in the network. If the negative-path is stable and the happy-path is not, you may have changed searchQuery, limit, or the chain structure.

A psychological point matters here: a smoke set does not have to “fail nicely.” It has to be understandable. Two negative requests are like two checkpoints on a map: “there should be a cliff here,” “there should be a desert here.” If there is suddenly an ocean where the desert should be, you may be lost.

7. Sample JSON and contract fixation

A smoke set does not invent a separate storage for sample JSON. It relies on the same files in src/main/resources/mock/catalog/: search-success.json, search-empty.json, details-success.json, and, if the provider really returns a JSON body for not-found, details-not-found.json.

If only a status and an empty body come back for {{missingBookId}}, do not invent a separate JSON just for symmetry. A short note next to the files is enough, stating that this scenario is fixed by the status and the absence of a body.

For each smoke request, it is useful to keep a short link to the corresponding sample in Description. An example in Postman can be saved as a visual hint, but the main support for mock mode remains the files in the repository.

8. Smoke-set run ritual

A smoke set is only good when it is used. That is why it should have a “run ritual” — simple and the same every time. No mysticism, no heroics, no “I’ll spend three hours setting it up just to check once.”

A practical scenario looks like this. You choose the active environment, checking it visually because Postman likes to stay quietly in the previous environment. Then you open 01 - Search - happy-path, click Send, look at the status and response shape, and make sure bookId was saved (you can see this in the Environment, where the variables are, or in the Postman Console if you used console.log). Then you open 02 - Details - happy-path, click Send, and check that it is really the card for the id you just found.

After that, you run the two negative requests. Not just “because they are there,” but to lock in the boundaries: an empty search query and a non-existent identifier. And that is it. At that point the smoke set is done. It should not be exhausting. It should give you confidence: “the contract is alive and understandable.”

If you discover that something has changed, you do not try to “fix everything.” You record what you observed: which status now comes back, what the body shape is, which fields disappeared or appeared. And you update the sample JSON if the change looks like a real contract change, not a random failure. That is contract discipline: do not panic, just carefully write down what the world did today.

9. Common mistakes in a Postman smoke set

Mistake #1: turning the smoke set into a museum of all experiments.
It is very easy to leave everything in the “smoke” folder: “header check,” “trying another parameter,” “and here I was looking at what happens if...”. Within a week, it stops being a smoke set and becomes a junk drawer. Keep only the requests in “smoke” that you are ready to run regularly, quickly, and without internal resistance.

Mistake #2: a dependent request sits before its data source.
If Details is above Search, you are almost guaranteed to click the wrong thing one day, get an error, and spend time figuring out “what broke.” This is not an API bug, it is an order bug. Numbering like 01/02, or at least an explicit order in the name, is a simple way to make the collection friendly to a tired human.

Mistake #3: baseUrl lives in different formats, and requests break on “concatenation.”
When baseUrl ends with / in one environment and not in another, you get either a double slash or “stuck together” URL parts. This is a very annoying class of errors because it looks like “the API went down,” while in reality your string went down. Decide once: baseUrl without a trailing slash — and then stop arguing with yourself.

Mistake #4: the chained request is not resilient to an empty search result.
If in Tests you immediately write body.items[0].id, then with an empty list you get a script error instead of honest behavior. A smoke set is good precisely because it should be calm and predictable: no items means no saving bookId, and no pretending that the world owes us a result.

Mistake #5: the negative path is chosen randomly and sometimes becomes the happy path.
The request books/BK-999 seems “definitely non-existent” until one day it turns out to exist. And suddenly you are “checking not found” but get a normal object instead — and start suspecting that the catalog is broken. For the negative path, choose deliberately artificial values like DOES_NOT_EXIST so that the scenario does not depend on the randomness of the data.