PlaySpec

• 

  PlaySpec flow

• 

  Generated Playwright Project

Inspiration

After a couple of years working as a backend developer, dealing with OpenAPI specifications became a daily routine, updating the docs whenever the API changed, then manually writing tests to reflect those same changes, then keeping both in sync as the codebase evolved. It's the kind of repetitive cycle that slowly drains you. The spec already defines the contract, so the question became obvious: why am I still writing tests by hand?

What it does

PlaySpec takes an OpenAPI/Swagger YAML/JSON file and turns it into a ready-to-run Playwright test project, delivered as a zip download. Before generating anything, it runs a validation pass that surfaces errors and warnings directly in the UI, so you know exactly what's wrong with your spec upfront. A frontend interface lets you upload your file and interact with the whole pipeline without touching a terminal!

How we built it

The backend is an Express service in Node.js that parses the OpenAPI document, walks every path and operation, and emits structured Playwright test files grouped by resource. The frontend is a purpose-built interface that connects to the backend APIs, handles file upload, displays validation feedback, and triggers the zip download, all in one flow.

Challenges we ran into

Real-world OpenAPI specs are inconsistent in ways that are hard to anticipate. Missing response schemas, ambiguous status codes, paths with no operations, parameters defined in unexpected places, every edge case required a deliberate decision about what to generate and what to flag. Getting the output to feel written rather than templated took significantly more iterations than expected.

Accomplishments that we're proud of

The validation layer is something I am genuinely proud of. Rather than silently generating broken tests or refusing to process an imperfect spec, PlaySpec gives you actionable feedback before committing to output. It makes the tool usable on messy, real-world specs, not just clean demo files.

What we learned

How expressive and how inconsistent OpenAPI specs can be in practice. Building a parser that handles the full surface area of the spec format, rather than just the happy path, forced a much deeper understanding of the standard than years of writing specs ever did.

What's next for PlaySpec

There are a few known limitations that are already on the roadmap. First, PlaySpec currently does not support OAuth2 authentication schemes, adding proper OAuth2 handling is a priority for the next iteration. Second, file size is currently capped at 5MB to guard against potential abuse and resource exhaustion; as the infrastructure matures, this limit can be revisited to support larger, more complex specs. Finally, the current deployment runs on Heroku Eco dynos, which come with real constraints around speed and concurrency. To work around this, a queue system has been added that supports up to 100 concurrent users, a wait queue of up to 300, and a hard rejection beyond that threshold until space opens up. Scaling the underlying infrastructure would directly lift all of those limits. The core engine is solid, it's mostly a matter of giving it the resources to match its potential.

Built With

• express.js
• heroku
• node.js
• react
• typescript