feat: add geckodriver to factory process

[MikeMcC399]

• closes Add geckodriver to factory process #1351

Situation

The mozilla/geckodriver is required to test Firefox. It is not part of the Firefox distribution, nor is it included in Cypress. If the driver is unavailable, then testing against Firefox fails. This is typically the case in an air-gapped environment.

If an attempt is made to run Cypress against a Firefox browser in a Cypress Docker container using cypress/browsers or cypress/included images, Cypress tries to download mozilla/geckodriver. In an air-gapped environment (no Internet access) the download fails and it is not possible to test against Firefox. The same applies to any Docker images built for Firefox with the current version of cypress/factory.

Secondly, in a regular environment with Internet connectivity, and no cached version of the mozilla/geckodriver stored in the Docker image, the driver version defaults to the latest, which means that the test configuration with Firefox is non-deterministic.

Assessment

Cypress uses the npm wrapper package geckodriver, bundled into the Cypress binary, in order to ensure the availability of the mozilla/geckodriver driver for Firefox testing.

By manually installing the mozilla/geckodriver in a Docker build process, and then setting the geckodriver environment variable GECKODRIVER_PATH, the wrapper package is instructed not to download and to use the locally stored driver instead.

If the mozilla/geckodriver can first be built into a Cypress Docker image in an environment with Internet connectivity, the Docker image can later be used in an environment without Internet to test against Firefox.

Change

Introduce a new Cypress build parameter GECKODRIVER_VERSION to direct the Cypress factory build process to install the corresponding version of mozilla/geckodriver into a Cypress Docker image being built. The driver is stored in the GECKODRIVER_PATH /opt/geckodriver/geckodriver.

The published images cypress/browsers and cypress/included are left unchanged, with no geckodriver pre-installed. An enhancement to these images is left for a follow-on PR.

This is a backwards-compatible feature addition.

Detailed changes

• Bump FACTORY_VERSION

• Add documentation to factory/README.md with new GECKODRIVER_VERSION section

• Update the CONTRIBUTING document

• Add the Cypress Docker parameter GECKODRIVER_VERSION to factory/.env to specify a version of the driver package mozilla/geckodriver from mozilla/geckodriver in the Cypress Docker factory build process. The default is set to the current latest version 0.36.0.

• Add install scripts for mozilla/geckodriver to the cypress/factory image so that the installation is compatible with use by the npm wrapper package geckodriver bundled in the Cypress binary (see https://github.com/cypress-io/cypress/blob/develop/packages/server/package.json) since cypress@13.15.1.

• Use new install scripts in factory/factory.Dockerfile, setting GECKODRIVER_PATH to /opt/geckodriver/geckodriver

• Harmonize the use of platformFilename for Firefox and geckodriver scripts. (Filename conventions are different for the two different package downloads.)

• Add new build compose services to factory/docker-compose.yml and to factory/test-project/docker-compose.yml

• Add CircleCI tests

• Add Dockerfile.factory to the following example directories to allow easier local testing:

  • examples/basic
  • examples/basic--mini
  • examples/firefox-esr

[cypress-app-bot]

• Create a Draft Pull Request if your PR is not ready for review. Mark the PR as Ready for Review when you're ready for a Cypress team member to review the PR.

[MikeMcC399]

Preview documentation

• https://github.com/MikeMcC399/cypress-docker-images/blob/add/factory-geckodriver/factory/README.md#geckodriver_version

[MikeMcC399]

Tests

CircleCI tests

Include additional test-factory-cypress-included-firefox-geckodriver tests for amd64 and arm64

Local tests

Test with Docker Desktop Linux 4.41.2 under Ubuntu 24.04.2 LTS, amd64

cd factory
docker compose build factory
cd ..

Build tests

cd examples/basic
docker build -f Dockerfile.factory --build-arg GECKODRIVER_VERSION=0.36.0 -t firefox-test .
cd ../..

• use --progress plain to see skipped messages
• use --no-cache to repeat test

GECKODRIVER_VERSION	Build message
0.36.0	Success
0.34.0	Success
0.99.0	Fail 404 Not Found
0.33.0	Skip

Run tests

Build custom images with network connected:

Edit: updated builds to latest versions

cd examples/basic
npm ci
docker build -f Dockerfile.factory \
--build-arg FIREFOX_VERSION=138.0.4 --build-arg GECKODRIVER_VERSION=0.36.0 \
-t firefox-browsers-test .

cd ../basic-mini
docker build -f Dockerfile.factory \
--build-arg CYPRESS_VERSION=14.4.0 --build-arg FIREFOX_VERSION=138.0.4 --build-arg GECKODRIVER_VERSION=0.36.0 \
-t firefox-included-test .

docker build -f Dockerfile.factory \
--build-arg CYPRESS_VERSION=13.15.0 --build-arg FIREFOX_VERSION=138.0.4 \
-t firefox-included-13.15.0-test .

cd ../firefox-esr
npm ci
docker build -f Dockerfile.factory --build-arg GECKODRIVER_VERSION=0.36.0 \
-t firefox-esr-test .

cd ../..

Disconnect network and run each image:

cd examples/basic
docker run -it --rm --entrypoint bash -v .:/app -w /app firefox-browsers-test -c "npx cypress run -b firefox"

cd ../basic-mini
docker run -it --rm --entrypoint cypress -v .:/app -w /app firefox-included-test run -b firefox
docker run -it --rm --entrypoint cypress -v .:/app -w /app -u node firefox-included-test run -b firefox # test non-root
docker run -it --rm --entrypoint cypress -v .:/app -w /app firefox-included-13.15.0-test run -b firefox

cd ../firefox-esr
docker run -it --rm --entrypoint bash -v .:/app -w /app firefox-esr-test -c "npx cypress run -b firefox"

cd ../..

[AtofStryker]

@MikeMcC399 I'm hoping to take a look at this either today or tomorrow

[MikeMcC399]

Re-tested locally with latest commit and running containers successfully without network connection.

[AtofStryker]

Gave everything a test locally. This looks great @MikeMcC399. Thank you!