An (even more) minimal way to test API routes
alemi2024-10-20 15:41
postwoman
I have seen postman used in a lot of places and by a lot of people, but I've never really understood it.
Wouldn't I be better off using curl and maybe scripting some requests from the terminal? Why would I need to download a dedicated software for that?
Also electron isn't exactly lightweight, so I've always steered away.
My current job at the time however put a lot of emphasis on testing, and introduced me to test-heavy workflows. At that point I saw postman usefulness: most value comes from the underlying collection! Developers share one and added routes they would work on. Once we had tested our code "from the inside" with unit and integration tests, we would send it to staging and test if "from the outside", running all requests in the postman collection.
This is great! However newer postman versions require me to register an account to be able to use the collection features, and once you're logged in, everything is kept in sync with their servers automatically.
This is awful! Why would you do that! I could not find an option to disable such feature at the time, and it was a huge dealbreaker: we can't have company internal structure and tokens just sitting on postman servers like that. What the hell!
So I decided to write my own solution. The collection format is just a json file, with proper documentation. Making requests is easy enough. Loading secrets can be done from the shell environment.
And just like that, the first version of postwoman was born! Why postwoman? Because we need more women in tech (:
I eventually found a rust library handling postman collection deserialization, so I could focus on running all tests.
This doesn't provide all features postman supports, only a subset is actually used, and it's not scriptable due to the weird print format. But it works, if you have a simple collection and would rather not use postman, consider using postwoman! If it doesn't do what you need, send a PR my way!
reborn
Original attempt ended up not being as useful as i'd like: making a CLI interface that works well for both sending and building requests is rather complex and the postman collection format is a mess.
So I decided to start anew: the v0.3 version completely dumped postman format and json, starting from scratch.
Routes are now defined in toml files, way easier to manage by hand, and can be structured in a tree thanks to import statements.
The main CLI tool no longer attempts to maintain your collection for you, it just reads it and runs it!
I'm way more fond of this approach: editing endpoints in GUI apps is annoying and now I can leverage my editor to quickly define all I need. Plus, because it's just a plain file tree, it's super easy to keep organized and even put it in git!
There is a super simple testing framework built in with extractors and expected results: just select your fields with JQ syntax and assert it equals to your expectations. It's also possible to just check status code, or to not check at all and just extract response fields or headers.
Just like before, all routes can contain variables which will be replaced at runtime from current environment.