Enable devs to build managed & ergonomic env var access on top of Cypress, by surfacing the built-in environment resolution logic in node

[adamscybot]

What would you like?

This request is what I believe to be the minimal requirement to enable a developer to implement certain use cases themselves in a sensible and extendable way.

The wider requirement that drives this is perhaps interesting in it itself, and will become evident. But I realise Cypress going further to cover that wider req would be a bigger deal and it would reach into "opinionated" territory, and so I am scoping my request to what would be needed in order for it to be better served in user-land. Thankfully, I think this is fairly minimal, but I want to explain why you'd want such a granular enhancement, so I've provided the wider context.

When a user calls Cypress.env([key]), they are receiving a value that has been processed by some internal Cypress logic. Cypess.env is currently accessible only inside the spec file. According to my understanding, this logic:

• Takes all the different ways Cypress can ingest environment variables, and applies some logic that amounts to defining the precedence of each of those that results in the final value.
• Does some type coercions, like converting number-like strings to numbers, and boolean-like strings to booleans etc.

I would like a way to call into that same resolution logic statically, but from the node backend.

Why is this needed?

On extensive, distributed and complex systems, I have regularly found that:

• The number of env vars can grow to a point where they become difficult to manage and as an engineering team you want to bring into order and introduce some constraints.
• You want to build in some level of type-safe validation of the env vars to avoid wasted resources, time, and frustration; but you don't want to block every spec on a single env var misconfig that may actually only matter to a smaller subset of tests anyway. You don't want to upfront and redundantly have the dev declare those affected tests in the node back end though.
• Despite that, you still want to stop that relevant subset of tests that do rely on invalid vars early and log that there is no point continuing; whilst letting the unaffected ones go on.
• You want to commit multiple different variations of the Cypress config (perhaps for several different deployment configuration). Each contain different values in the env object, which serve as defaults (that ought to be overridable by any of the Cypress env ingest methods), and you also would like those to be type safe against same "schema".
• You'd like to provide a nice DX that enables a dev to see when env vars were read in when that happens, whilst still allowing them to be referenced statically in the spec file both inside and outside of the test context (top level, above top describe()) like how Cypress.env works today. We've done this via some crazy but really good impl that that's using object proxy wrappers that in turn use Cypress.log.
• Crucially, you don't want to divert from the different ways Cypress can ingest environment variables (--env, CYPRESS_, env: in config etc), because it breaks dev expectations.

I don't want to mess up the way Cypress ingests env vars and break dev expectations. I also need those different ways for CI vs local scenarios anyway. For that reason, I can only implement this "env processing/validation" layer sensibly on the browser side since the only way to resolve the env vars in a way which matches the expectations of anyone reading the Cypress docs & also remains forwards-compatible, is to build a mechanism that involves the browser. Since only the browser can access Cypress.env and only Cypress.env can seemingly access the underlying logic.

That could be ignored but that would mean either:

• Not bother with expectations and support only a certain ingest method and opt out of Cypress env ingest heuristics.
• Or -- copy the internal env var resolution logic of cypress on server side (bad)

To do it properly, you need to call Cypress.env() on the browser somewhere in the flow, which is also an issue from a security perspective if looking to manage secrets in a certain way. Everything I said up to this point is doable (I've done it). But only if you are good with sending all the env vars to the browser and having the schema in that browser bundle, just for calling Cypress.env() without having some pseudo-implementation of the resolution logic. Needing to do this brings about headaches also in wanting it both browser side and node side, since some logic might only be practically available in node. And I'd rather not deal with serialisation of some validation schema (think Zod).

I won't go into more detail since the userland for this stuff is quite complex and it would remain so after. The whole flow of it and complexities are something I don't expect Cypress to solve. Actually, some of this can be solved at build time in the preprocessor. But not if you wanna keep the nice Cypress env ingest but the env var resolution logic remains only in the browser runtime.

The ability to solve it nicely is hindered just by that the default env var resolution code is not statically accessible from node. Not necessarily as a mirror of Cypress.env() (by the way I realise that also allows a set operation, and so that might introduce confusion, since nothing here needs a no-effort "universal" env between both sides). Even a totally separate unsupported static import available to node for advanced use that has no direct impact on Cypress.env would be great, in order to build our own impl properly. Perhaps it could be in a new meta object provided to setupNodeEvents?

It'd be amazing if this whole thing was considered at a higher level, but tbh even an escape hatch would be great.

I will buy Cypress team doughnuts. Screenshot it.

Also if there's an escape hatch I don't know about, that would be legendary.

Other

I am a long time Cypress user. I have introduced and put it into the pipeline in several companies; and these patterns have emerged multiple times over that time. I have implemented them, but it's only doable in a suboptimal way if you don't want to reimplement the Cypress env resolution; self-limit to a certain way of providing the vars that breaks user expectations; or maintain security.

[jennifer-shehane]

@adamscybot I have seen pretty complex uses of Cypress.env also. The security aspect bleeds over into another discussion of us needing to expose more ways to mask sensitive data, so I'd expect that to come in some way in a future release.

Can you show your workaround for this today? Psuedo code is fine also.

[cypress-app-bot]

This issue has not had any activity in 180 days. Cypress evolves quickly and the reported behavior should be tested on the latest version of Cypress to verify the behavior is still occurring. It will be closed in 14 days if no updates are provided.