Cypress Structure: What It Means for Humans and AI

In testing frameworks like Cypress, the use of a POM Hybrid structure is promoted by some users, and I am one of those users—but I put my own twist on it. Along with Page Object files, I also have my own structural quirks, like creating separate `commands.js` and `apiCommands.js` files, with API assertions and logs strategically sprinkled in. Pre-AI, having a structured approach seemed opinionated and very individualistic; post-AI, it feels a bit like when I learned guitar: I started on an acoustic to hear and feel every note clearly, building a strong foundation. Later, switching to an electric guitar was like adding a supercharger—everything amplified. Similarly, my structured testing habits helped set the stage, and adding a rockstar AI assistant supercharges the process, making test writing faster, clearer, and more collaborative for both humans and AI.


The POM Hybrid Structure: A Foundation for Clarity

My approach to Cypress testing mirrors the strategy I learned with that acoustic guitar: clarity and transparency. It’s a Page Object Model (POM) Hybrid with some useful preferences:

  • The `pages/` Directory: Houses POM files like `LoginPage.js`, encapsulating selectors and actions (e.g., `loginPage.fillUsername()`).
  • The `commands.js` File: Handles reusable UI workflows, such as `cy.loginViaUI()`, orchestrating multi-page user journeys.
  • The `apiCommands.js` File: Contains API-driven commands like `cy.loginViaAPI()`, with response status assertions and logs (e.g., `cy.log('LOGGING IN VIA API WITH USERNAME: ' + username)`), making it easy for AI to understand intent.
  • Feature-Based Directories: Arranged as `e2e/ui/authentication/` or `e2e/ui/calendar/` for intuitive organization.

This structure—seen in my Cypress demo tests on `decibeltribe.com`—keeps concerns separate, making tests easier to target, more stable, and easier to maintain, not just for humans, but for AI maintainers as well.


Why This Structure Benefits Humans and AI

For humans, this structure has an upfront cost but is a lifesaver in the long run: the separation of UI and API logic ensures speed (bypassing slow UI flows for setup), stability (API calls are less brittle than UI interactions), and clarity (clean, maintainable tests). In today’s world, where AI is a coding partner, this structure is a goldmine. The organized hierarchy of `fixtures/`, `e2e/ui/`, `pages/`, and `apiCommands/` provides AI with a clear map of the project. Adding `cy.log` and API response assertions in `apiCommands.js` gives AI the context it needs to understand test intent, making it easier for tools to debug, optimize, or expand your work. I’ve seen this in action with my hobby projects. Beyond immediate benefits, project structure and code structure—with some kind of type notation—aren’t just good habits and communication tools for your human co-conspirators; they help guide the autonomous mind of AI. You’ll now have AI doing code reviews, AI developers working side by side, and even whole teams of AI agents potentially maintaining the legacy codebase while humans build the new codebase. Making files smaller and easier to modify and find is key. Sure, AI may be smarter than any human ever, but that doesn’t mean it doesn’t benefit from structure—clear organization helps AI navigate and modify codebases efficiently, ensuring long-term reliability.


Tips for Structuring Tests in the AI Era

  • Separate Concerns: Keep UI and API logic distinct for clarity and maintainability.
  • Add Logs and Assertions: Use `cy.log` and response assertions in API commands to enhance visibility for humans and context for AI.
  • Organize Intuitively: Structure your project logically with small, modular files to help AI navigate and maintain codebases.
  • Balance Speed and Depth: Use API commands for fast setups, but don’t skimp on documentation and type notation for AI and human users.

This Cypress structure doesn’t just help me write faster, more reliable tests; it empowers AI to be a better coding partner, reviewer, and maintainer. By building a strong foundation with separate UI and API commands, adding `cy.log` and assertions, and organizing files logically with type notation, we create a framework that’s clear for humans and rich with context for AI. The tech industry moves fast, but with the right structure, we can level up our tests, collaboration, and even legacy maintenance—human and AI alike.

← Back to Blog List
@