Clarify Cypress NPM vs Docker image dependency in Readme?

[YoungElPaso]

Hi, I've been working with Cypress via NPM directly on the host, as well as in Gitlab CI via the official cypress/included Docker images for a while, and now I'm trying to resolve a few issues with managing dependencies and this repo seems pertinent.

From what I've read here: https://docs.cypress.io/guides/continuous-integration/introduction#Official-Cypress-Docker-Images and in my own experience, there's a (irreconcilable?) issue with trying to run Cypress on your host (and thus including it in package.json) and running it in Docker (as this repo does) and NOT including it.

The official docs explicitly say not to mount your node modules in the cypress/included container - the binary will not be found - and I think I get it, that's if you've got Cypress in package.json and installed in host, there will be a confict with what is installed in the container already. This could be compounded by the fact that you might also have a version mismatch between Cypress in package.json and the tag and version you've selected for the image.

So the obvious solution to that issue is what you've done here: do not include a version of Cypress on the host at all. No host Cypress, no conflict, just rely on what the official image has already brought to the table, but still rely on package.json for plugins, which can be dev, or perhaps even optional dependencies. So in this case, the container calls all the shots.

However, does this not raise another issue: if there's no cypress version in package.json, 1) how should we specify that we depend on Cypress (perhaps we just don't) and 2) if we don't specify a version, do we not risk having a incompatiblity between plugins? In essence when everything is in package.json I can rely on having one place to manage dependencies.

Maybe there is no easy solution, maybe as in my case, a Dockerfile will be the only way to specify the version of Cypress we use (in this case, only that via Docker image). But, given the official docs seem ambiguous about this and this demo repo seems to suggest going the Docker-only route, I'm left wondering if either the official docs could be more clear or if this repo Readme should have some more details surrounding this dependency management issue.

So, basically, is there an official opinion or recommendation on this? If, so could this be made more clear in the docs?

[YoungElPaso]

I should add, I've explored the option of implementing an NPM script to build the Docker image from cypress/included:xxx where 'xxx' might be a build arg and I could supply the value of that arg by using an NPM_ environment variable for the version of Cypress found in package.json. That way, the package.json and docker image version would be synced, but that would only work well for specific versions, and seems like a bit of a hack.

It also doesn't sort out the node modules mounting issue where the binary isn't found, though I also realize in that case I could run npx cypress install to make sure the binary in the cache is found. But again, that seems slightly hackish.

[YoungElPaso]

In case anyone else has this issue, here's what I did in the end:

• Added a dependency from my main package, "A" to a new, local dependency "B" using the file path for B in package.json
• B is a local npm package that lives in a sub-directory of A
• B defines a shell script that checks if Docker is installed, and if so, can run the image I want (one based on cypress/included)
• B sets this shell script as an entry for 'bin' in it's package.json so that A can use it via npm scripts etc
• So A depends on B which provides Docker and B can be tracked (and even made external at some point, in it's own repo etc) and included as a proper dependency
• If I don't need Docker anymore, I just stop including B as a dep.