Field note
When integration tests should leave the end-to-end folder
Teams often park every new scenario in the browser suite because that is where the last incident was caught. Over time the folder becomes a parallel application: login helpers, database seeds, and API stubs hidden inside UI steps. The suite slows down, yet engineers still distrust it because failures are ambiguous.
The journey vs the contract question
Ask whether a failure would matter to a customer watching the screen. If the assertion is really about whether service B returns the correct VAT calculation when service A sends a malformed idempotency key, the customer never sees that path directly. That belongs closer to the HTTP boundary.
Signals it is time to move
- The spec never interacts with visible UI state after authentication—it only waits on network calls.
- You duplicate the same API payload setup in three UI files.
- Failures mention timeouts on XHR rather than missing elements.
- Product owners cannot describe the user story without you translating it into backend jargon.
What to keep in end-to-end
Retain thin paths that prove critical journeys: signup, payment confirmation, permission changes that alter navigation. One happy path per journey is enough if lower layers carry the combinatorics.
Migration habit
When moving a spec, delete the UI version in the same pull request that adds the integration test. Leaving both “temporarily” reintroduces drift within a sprint. Name tests after the business rule, not the button label, so future readers know why the check exists.
Test Architecture Review engagements include a tagged inventory that marks candidates for this kind of move.