fix: impove params handling (#106)

- export CurrentsRunAPI
- make  params compatible with CypressCommandLine.CypressRunOptions
- remove mandatory params from CurrentsRunAPI

packages/cypress-cloud/index.ts

@@ -2,13 +2,13 @@ import "source-map-support/register.js";
 
 import { run as internalRun } from "./lib/run";
 import { CurrentsRunAPI } from "./types";
-
+export type { CurrentsRunAPI } from "./types";
 /**
  * Run Cypress tests with a cloud service of your choice and return the results
  *
  * @augments CurrentsRunAPI
- * @returns {CypressCommandLine.CypressRunResult} The test results, or undefined if no tests were run
+ * @returns {CypressCommandLine.CypressRunResult | undefined} The test results, or undefined if no tests were run
  */
-export function run(params: CurrentsRunAPI) {
+export function run(params?: CurrentsRunAPI) {
   return internalRun(params);
 }

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

@@ -66,13 +66,44 @@ describe("validateParams", () => {
     );
   });
 
+  it("should transform string tag", () => {
+    const params: CurrentsRunParameters = {
+      batchSize: 10,
+      testingType: "e2e",
+      cloudServiceUrl: "http://localhost:3333",
+      projectId: "abc123",
+      recordKey: "def456",
+      tag: "a,b,c",
+    };
+
+    expect(validateParams(params)).toMatchObject({
+      tag: expect.arrayContaining(["a", "b", "c"]),
+    });
+  });
+
+  it("should transform string[] tag", () => {
+    const params: CurrentsRunParameters = {
+      batchSize: 10,
+      testingType: "e2e",
+      cloudServiceUrl: "http://localhost:3333",
+      projectId: "abc123",
+      recordKey: "def456",
+      tag: ["a", "b"],
+    };
+
+    expect(validateParams(params)).toMatchObject({
+      tag: expect.arrayContaining(["a", "b"]),
+    });
+  });
+
   it("should return validated params if all required parameters are provided", () => {
     const params: CurrentsRunParameters = {
       batchSize: 10,
       testingType: "e2e",
       cloudServiceUrl: "http://localhost:3333",
       projectId: "abc123",
       recordKey: "def456",
+      tag: [],
     };
 
     expect(validateParams(params)).toEqual({

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

@@ -54,22 +54,24 @@ export function resolveCurrentsParams(
 }
 
 export const projectIdError = `Cannot resolve projectId. Please use one of the following:
+- provide it as a "projectId" property for "run" API method
 - set CURRENTS_PROJECT_ID environment variable
-- set "projectId" in "currents.config.js" file
-- provide it as a "projectId" property for "run" API method`;
+- set "projectId" in "currents.config.js" file`;
 
 export const cloudServiceUrlError = `Cannot resolve cloud service URL. Please use one of the following:
+- provide it as a "cloudServiceUrl" property for "run" API method
 - set CURRENTS_API_URL environment variable
-- set "cloudServiceUrl" in "currents.config.js" file
-- provide it as a "cloudServiceUrl" property for "run" API method`;
+- set "cloudServiceUrl" in "currents.config.js" file`;
 
 export const cloudServiceInvalidUrlError = `Invalid cloud service URL provided`;
 
 export const recordKeyError = `Cannot resolve record key. Please use one of the following:
+
+- pass it as a CLI flag '-k, --key <record-key>'
+- provide it as a "recordKey" property for "run" API method
 - set CURRENTS_RECORD_KEY environment variable
-- pass it as a cli flag '-k, --key <record-key>'
 - set "recordKey" in "currents.config.js" file
-- provide it as a "recordKey" property for "run" API method`;
+`;
 
 export function validateParams(
   _params: CurrentsRunParameters
@@ -108,10 +110,24 @@ export function validateParams(
       throw new Error("Missing required parameter");
     }
   });
-  debug("validated currents parametes: %o", params);
+  params.tag = parseTags(params.tag);
+  debug("validated currents params: %o", params);
   return params as ValidatedCurrentsParameters;
 }
 
+function parseTags(tagString: CurrentsRunParameters["tag"]): string[] {
+  if (!tagString) {
+    return [];
+  }
+  if (Array.isArray(tagString)) {
+    return tagString.filter(Boolean);
+  }
+  return tagString
+    .split(",")
+    .map((tag) => tag.trim())
+    .filter(Boolean);
+}
+
 /**
  *
  * @returns Cypress non-empty options without the ones that are not relevant for the runner

packages/cypress-cloud/lib/run.ts

@@ -14,7 +14,7 @@ import { getSpecFiles } from "./specMatcher";
 
 const debug = Debug("currents:run");
 
-export async function run(params: CurrentsRunParameters) {
+export async function run(params: CurrentsRunParameters = {}) {
   debug("run params %o", params);
 
   const validatedParams = validateParams(params);

packages/cypress-cloud/lib/specMatcher/getSpecFiles.ts

@@ -1,11 +1,14 @@
-import { ValidatedCurrentsParameters } from "../../types";
+import {
+  CurrentsRunParameters,
+  ValidatedCurrentsParameters,
+} from "../../types";
 import { MergedConfig } from "../config/config";
 import { warn } from "../log";
 import { findSpecs } from "./specMatcher";
 
 const getSpecPattern = (
   configPattern: MergedConfig["specPattern"],
-  explicit?: string[]
+  explicit?: CurrentsRunParameters["spec"]
 ) => explicit || configPattern;
 
 export const getSpecFiles = async ({

packages/cypress-cloud/lib/ws.ts

@@ -1 +1,2 @@
 // plug for future websocket server
+export {};

packages/cypress-cloud/support/index.ts

@@ -1 +1,2 @@
 /// <reference types="Cypress" />
+export {};

packages/cypress-cloud/types.ts

@@ -134,7 +134,7 @@ export type CurrentsRunParameters = StrippedCypressModuleAPIOptions & {
   /** The URL of the currents server to use. If not specified, will use the one from currents.config.js */
   cloudServiceUrl?: string;
   /** The environment variables to use for the run */
-  env?: Record<string, unknown>;
+  env?: object;
   /** The group id to use for the run */
   group?: string;
   /**  The record key to use */
@@ -143,19 +143,17 @@ export type CurrentsRunParameters = StrippedCypressModuleAPIOptions & {
   parallel?: boolean;
   /** The project ID to use. */
   projectId?: string;
-  /** The array of spec patterns for the execution */
-  spec?: string[];
-  /** The array of tags for the execution */
-  tag?: string[];
+  /** Comma-separated string or an array of spec glob pattern for the execution */
+  spec?: string | string[];
+  /** Comma-separated string or an array of tags */
+  tag?: string | string[];
   /** "e2e" or "component", the default value is "e2e" */
   testingType?: TestingType;
 };
 
-// User-facing interface
-export interface CurrentsRunAPI extends CurrentsRunParameters {
-  readonly projectId: string;
-  readonly recordKey: string;
-}
+// User-facing interface `run` interface
+// We can resolve the projectId and recordKey from different sources, so we can't really enforce them via the type definition
+export interface CurrentsRunAPI extends CurrentsRunParameters {}
 
 // Params after validation and resolution
 export interface ValidatedCurrentsParameters extends CurrentsRunParameters {
@@ -164,4 +162,5 @@ export interface ValidatedCurrentsParameters extends CurrentsRunParameters {
   readonly batchSize: number;
   readonly testingType: TestingType;
   readonly recordKey: string;
+  readonly tag: string[];
 }