feat: add --cloud-config-file

.github/README.md

@@ -29,7 +29,7 @@ Install the package:
 npm install cypress-cloud
 ```
 
-- Create a new configuration file: `currents.config.js|mjs|cjs` in the Cypress project’s root (Using ESM project? See the guide below).
+- Create a new configuration file: `currents.config.js|mjs|cjs` in the Cypress project’s root. Use `--cloud-config-file` to explicitly provide the configuration file. Using ESM project? See the guide below.
 - Set the `projectId` and the record key obtained from [Currents](https://app.currents.dev) or your self-hosted instance of Sorry Cypress:
 
 ```js
@@ -88,14 +88,24 @@ module.exports = {
 };
 ```
 
-`cypress-cloud` will search for a configuration file at the project's root location (defined with `-P --project` CLI option) in the following order:
+### Configuration File Discovery
 
-- `currents.config.js`
-- `currents.config.cjs`
-- `currents.config.mjs`
+`cypress-cloud` will search for a configuration file as follows:
+
+- if `--cloud-config-file <string>` is defined, use its value
+
+  - use it as-is for absolute paths
+  - if it's a relative path, use the project's root location (defined with `-P --project` CLI option) as the base directory
+
+- otherwise, use the default filenames in the project's root location (defined with `-P --project` CLI option) in the following order:
+  - `currents.config.js`
+  - `currents.config.cjs`
+  - `currents.config.mjs`
 
 The configuration file will be read using [`import()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) expression. Please make sure to use the correct syntax if you're using ESM modules (see the guide below).
 
+### Configuration Overrides
+
 You can override the configuration values via environment variables:
 
 - `CURRENTS_API_URL` - sorry-cypress users - set the URL of your director service
@@ -106,7 +116,7 @@ The configuration variables will resolve as follows:
 
 - the corresponding CLI flag or `run` function parameter, otherwise
 - environment variable if exist, otherwise
-- `currents.config.js|cjs|mjs` value, otherwise
+- configuration file `currents.config.js|cjs|mjs` value, otherwise
 - the default value, otherwise throw
 
 ## Batched Orchestration
@@ -193,7 +203,7 @@ For ESM projects (`"type": "module"` in `package.json`) you can use one of the f
 - `currents.config.js` - ESM formatted file (i.e. no `require` statements)
 - `currents.config.mjs` - ESM formatted file (i.e. no `require` statements)
 
-Also, make sure that your `cypress.config.js|mjs|cjs|ts` is formatted accordingly. See examples at [`./e2e`](./e2e) directory.
+Also, make sure that your `cypress.config.js|mjs|cjs|ts` is formatted accordingly. See examples in [`./e2e`](./e2e) directory.
 
 ## Troubleshooting
 

packages/cypress-cloud/bin/lib/program.ts

@@ -97,6 +97,12 @@ export const createProgram = (command: Command = new Command()) =>
       new Option("--headed [bool]", "Run cypress in headed mode")
         .default(false)
         .argParser((i) => (i === "false" ? false : true))
+    )
+    .addOption(
+      new Option(
+        "--cloud-config-file <path>",
+        "Specify the config file for cypress-cloud, defaults to 'currents.config.js' and will be searched in the project root, unless an aboslue path is provided"
+      ).default(undefined)
     );
 
 export const program = createProgram();

packages/cypress-cloud/lib/config/__tests__/path.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "@jest/globals";
+import { defaultFilenames, getConfigFilePath, normalizePath } from "../path";
+
+describe("getConfigFilePath", () => {
+  it.each([
+    [
+      "should return the default config file paths",
+      { projectRoot: "root", explicitPath: undefined },
+      defaultFilenames.map((p) => normalizePath("root", p)),
+    ],
+    [
+      "should return relative path to config file",
+      { projectRoot: "root", explicitPath: "explicit" },
+      [normalizePath("root", "explicit")],
+    ],
+    [
+      "should return absolute path to config file",
+      { projectRoot: "root", explicitPath: "/users/a/c.js" },
+      ["/users/a/c.js"],
+    ],
+  ])("%s", (_title, { projectRoot, explicitPath }, expected) => {
+    expect(getConfigFilePath(projectRoot, explicitPath)).toMatchObject(
+      // @ts-expect-error
+      expected
+    );
+  });
+});

packages/cypress-cloud/lib/config/config.ts

@@ -1,10 +1,10 @@
 import Debug from "debug";
-import path from "path";
-import os from 'os'
+
 import { P, match } from "ts-pattern";
 import { DetectedBrowser, ValidatedCurrentsParameters } from "../../types";
 import { bootCypress } from "../bootstrap";
-import { warn } from "../log";
+import { info, warn } from "../log";
+import { getConfigFilePath } from "./path";
 
 const debug = Debug("currents:config");
 
@@ -35,13 +35,14 @@ const defaultConfig: CurrentsConfig = {
 };
 
 export async function getCurrentsConfig(
-  projectRoot?: string
+  projectRoot?: string,
+  explicitConfigFilePath?: string
 ): Promise<CurrentsConfig> {
   if (_config) {
     return _config;
   }
 
-  const configFilePath = getConfigFilePath(projectRoot);
+  const configFilePath = getConfigFilePath(projectRoot, explicitConfigFilePath);
   // try loading possible config files
   for (const filepath of configFilePath) {
     const config = match(await loadConfigFile(filepath))
@@ -51,6 +52,7 @@ export async function getCurrentsConfig(
 
     if (config) {
       debug("loaded currents config from '%s'\n%O", filepath, config);
+      info("Using config file: '%s'", filepath);
       _config = {
         ...defaultConfig,
         ...config,
@@ -113,12 +115,3 @@ export async function getMergedConfig(params: ValidatedCurrentsParameters) {
   debug("merged config: %O", result);
   return result;
 }
-
-function getConfigFilePath(projectRoot: string | null = null): string[] {
-  const prefix = projectRoot ?? process.cwd();
-  return [
-    "currents.config.js",
-    "currents.config.cjs",
-    "currents.config.mjs",
-  ].map((p) => `file://${path.resolve(prefix, p)}`);
-}

packages/cypress-cloud/lib/config/params.ts

@@ -13,7 +13,10 @@ const debug = Debug("currents:validateParams");
 export async function resolveCurrentsParams(
   params: CurrentsRunParameters
 ): Promise<CurrentsRunParameters> {
-  const configFromFile = await getCurrentsConfig(params.project);
+  const configFromFile = await getCurrentsConfig(
+    params.project,
+    params.cloudConfigFile
+  );
 
   debug("resolving currents params: %o", params);
   debug("resolving currents config file: %o", configFromFile);
@@ -163,6 +166,7 @@ export function getCypressRunAPIParams(
   return {
     ..._.pickBy(
       _.omit(params, [
+        "cloudConfigFile",
         "autoCancelAfterFailures",
         "cloudServiceUrl",
         "batchSize",

packages/cypress-cloud/lib/config/path.ts

@@ -0,0 +1,30 @@
+import isAbsolute from "is-absolute";
+import _ from "lodash";
+import path from "path";
+
+export const defaultFilenames = [
+  "currents.config.js",
+  "currents.config.cjs",
+  "currents.config.mjs",
+];
+export function getConfigFilePath(
+  projectRoot: string | null = null,
+  explicitConfigFilePath?: string
+): string[] {
+  const prefix = projectRoot ?? process.cwd();
+  if (
+    _.isString(explicitConfigFilePath) &&
+    isAbsolute(explicitConfigFilePath)
+  ) {
+    return [explicitConfigFilePath];
+  }
+  if (_.isString(explicitConfigFilePath)) {
+    return [normalizePath(prefix, explicitConfigFilePath)];
+  }
+
+  return defaultFilenames.map((p) => normalizePath(prefix, p));
+}
+
+export function normalizePath(prefix: string, filename: string): string {
+  return `file://${path.resolve(prefix, filename)}`;
+}

packages/cypress-cloud/lib/run.ts

@@ -78,8 +78,6 @@ export async function run(params: CurrentsRunParameters = {}) {
     browser: validatedParams.browser,
   });
 
-  divider();
-
   info("Discovered %d spec files", specs.length);
   info(
     `Tags: ${tag.length > 0 ? tag.join(",") : false}; Group: ${

packages/cypress-cloud/package.json

@@ -65,6 +65,7 @@
     "execa": "^5.1.1",
     "getos": "^3.2.1",
     "globby": "^11.1.0",
+    "is-absolute": "^1.0.0",
     "lil-http-terminator": "^1.2.3",
     "lodash": "^4.17.21",
     "nanoid": "^3.3.4",