@axinom/mosaic-e2e-page-model 0.2.5-rc.9 → 0.3.0-rc.0

package/src/managed-services/monetization-service/monetization-service.ts

@@ -0,0 +1,560 @@
+import { ActionLabel } from '@axinom/mosaic-e2e-ui-selectors';
+import { ManagedServiceModel } from '../managed-service-model';
+import { ClaimsEditor } from './claim-set-control';
+
+export interface SubscriptionPlanFilters {
+  subscriptionPlanTitle: string;
+}
+
+export interface ClaimSetFilters {
+  uniqueKey: string;
+}
+
+/** A model for the managed monetization service. */
+export class MonetizationService extends ManagedServiceModel {
+  /**
+   * This method navigates to the subscription plans explorer station.
+   * The management system must be loaded & signed in before using this method.
+   *
+   * The following steps will be taken:
+   * - Navigate to the home breadcrumb, then tiles: 'Monetization', 'Subscription Plans'
+   * - Wait for data to load
+   */
+  async navigateToSubscriptionPlans(): Promise<void> {
+    const { uiShell, uiManagedWorkflows } = this;
+    await uiShell.navigateToLandingPageTile('Monetization');
+
+    // click subscription plans tile
+    const label = 'Subscription Plans';
+    const tile = uiManagedWorkflows.hub.getTileByLabel(label);
+    try {
+      await tile.waitFor({ state: 'visible' });
+    } catch {
+      throw new Error(`Monetization hub tile '${label}' is not visible.`);
+    }
+    await uiShell.waitForPageTransition(tile.click());
+    await uiManagedWorkflows.list.waitForData();
+  }
+
+  /**
+   * This method navigates to the claim sets explorer station.
+   * The management system must be loaded & signed in before using this method.
+   *
+   * The following steps will be taken:
+   * - Navigate to the home breadcrumb, then tiles: 'Monetization', 'Claim Sets'
+   * - Wait for data to load
+   */
+  async navigateToClaimSets(): Promise<void> {
+    const { uiShell, uiManagedWorkflows } = this;
+    await uiShell.navigateToLandingPageTile('Monetization');
+
+    // click claim sets tile
+    const label = 'Claim Sets';
+    const tile = uiManagedWorkflows.hub.getTileByLabel(label);
+    try {
+      await tile.waitFor({ state: 'visible' });
+    } catch {
+      throw new Error(`Monetization hub tile '${label}' is not visible.`);
+    }
+    await uiShell.waitForPageTransition(tile.click());
+    await uiManagedWorkflows.list.waitForData();
+  }
+
+  /**
+   * This method navigates to a subscription plan details station by title.
+   * The management system must be loaded & signed in before using this method.
+   * If there is not exactly one matching subscription plan an exception will be raised.
+   *
+   * The following steps will be taken:
+   * - Navigate to the home breadcrumb, then tiles: 'Monetization', 'Subscription Plans'
+   * - Filter by title and click the subscription plan row action
+   * - Wait for the subscription plan details page to load
+   */
+  async navigateToSubscriptionPlanDetails(filterBy: {
+    /** A unique subscription plan title. */
+    title: string;
+  }): Promise<void> {
+    const { uiShell, uiManagedWorkflows } = this;
+    await this.navigateToSubscriptionPlans();
+
+    // filter to the item
+    await uiManagedWorkflows.filters
+      .getFilterByName('title')
+      .asFreeTextFilter()
+      .setValue(filterBy.title);
+    await uiManagedWorkflows.list.waitForData();
+
+    // Verify that there is exactly one matching row
+    if ((await uiManagedWorkflows.list.allVisibleRows.count()) !== 1) {
+      throw new Error(
+        `Failed to find exactly one subscription plan with title '${filterBy.title}'.`,
+      );
+    }
+
+    // navigate
+    await uiShell.waitForPageTransition(
+      uiManagedWorkflows.list.getRow(1).actionButton.click(),
+    );
+    await uiManagedWorkflows.form.waitForData();
+  }
+
+  /**
+   * This method navigates to a claim set details station by unique key.
+   * The management system must be loaded & signed in before using this method.
+   * If there is not exactly one matching claim set an exception will be raised.
+   *
+   * The following steps will be taken:
+   * - Navigate to the home breadcrumb, then tiles: 'Monetization', 'Claim Sets'
+   * - Filter by unique key and click the claim set row action
+   * - Wait for the claim set details station to load
+   */
+  async navigateToClaimSetDetails(args: {
+    /** The claim set unique key. */
+    uniqueKey: string;
+  }): Promise<void> {
+    const { uiShell, uiManagedWorkflows } = this;
+
+    if (this.page.url().endsWith(`/monetization/claimsets/${args.uniqueKey}`)) {
+      // already on the correct page. do nothing
+      return;
+    }
+    await this.navigateToClaimSets();
+
+    // filter to the item
+    await uiManagedWorkflows.filters
+      .getFilterByName('key')
+      .asFreeTextFilter()
+      .setValue(args.uniqueKey);
+    await uiManagedWorkflows.list.waitForData();
+
+    // Verify that there is exactly one matching row
+    if ((await uiManagedWorkflows.list.allVisibleRows.count()) !== 1) {
+      throw new Error(
+        `Failed to find exactly one claim set with unique key '${args.uniqueKey}'.`,
+      );
+    }
+
+    // navigate
+    await uiShell.waitForPageTransition(
+      uiManagedWorkflows.list.getRow(1).actionButton.click(),
+    );
+    await uiManagedWorkflows.form.waitForData();
+  }
+
+  /**
+   * This method assigns a claim set to the subscription plan.
+   * The management system must be loaded & signed in before using this method.
+   * If the claim set does not exist, or is already added to this subscription plan then an exception will be raised.
+   *
+   * The following steps will be taken:
+   * - Navigate to the home breadcrumb, then tiles: 'Monetization', 'Subscription Plans'
+   * - Filter by title and click the subscription plan row action
+   * - Click the 'Claim Sets' action
+   * - Open the claim sets explorer modal, filter by key and select the first result
+   * - Click the 'previous' breadcrumb and wait for the subscription plan details station to load
+   */
+  async assignClaimSetToSubscriptionPlan(args: {
+    /** A unique subscription plan title. */
+    subscriptionPlanTitle: string;
+    /** The claim set unique key. */
+    claimSetUniqueKey: string;
+  }): Promise<void> {
+    const { uiShell, uiManagedWorkflows } = this;
+    await this.navigateToSubscriptionPlanDetails({
+      title: args.subscriptionPlanTitle,
+    });
+
+    await uiShell.waitForPageTransition(
+      uiManagedWorkflows.actions.getActionByLabel('Manage Claim Sets').click(),
+    );
+    await uiManagedWorkflows.form.waitForData();
+
+    // open modal
+    await uiManagedWorkflows.form
+      .getFieldByLabel('Claim Sets')
+      .asDynamicDataListField()
+      .dataList.dataEntryRow.addButton.click();
+    const modal = uiManagedWorkflows.form.modal.asSelectionExplorer();
+    await modal.waitToOpen();
+    await modal.list.waitForData();
+
+    // filter to the claim set
+    await modal.filters
+      .getFilterByName('key')
+      .asFreeTextFilter()
+      .setValue(args.claimSetUniqueKey);
+    await modal.list.waitForData();
+    if ((await modal.list.allVisibleRows.count()) !== 1) {
+      throw new Error('The claim set was not found or is already assigned.');
+    }
+
+    // assign the claim set
+    await modal.list.getRow(1).selectButton.click();
+    await modal.waitToClose();
+
+    // Back to subscription plan details
+    await uiShell.navigateToBreadcrumbPrevious();
+    await uiManagedWorkflows.form.waitForData();
+  }
+
+  /**
+   * This method removes a claim set assignment from a subscription plan.
+   * The management system must be loaded & signed in before using this method.
+   * If the claim set is not assigned to this subscription plan then an exception will be raised.
+   *
+   * The following steps will be taken:
+   * - Navigate to the home breadcrumb, then tiles: 'Monetization', 'Subscription Plans'
+   * - Filter by title and click the subscription plan row action
+   * - Click the 'Claim Sets' action
+   * - Unassign the claim set using the inline menu
+   * - Click the 'previous' breadcrumb and wait for the subscription plan details station to load
+   */
+  async removeClaimSetFromSubscriptionPlan(args: {
+    /** A unique subscription plan title. */
+    subscriptionPlanTitle: string;
+    /** The claim set unique key. */
+    claimSetUniqueKey: string;
+  }): Promise<void> {
+    const { uiShell, uiManagedWorkflows } = this;
+    await this.navigateToSubscriptionPlanDetails({
+      title: args.subscriptionPlanTitle,
+    });
+
+    await uiShell.waitForPageTransition(
+      uiManagedWorkflows.actions.getActionByLabel('Manage Claim Sets').click(),
+    );
+    await uiManagedWorkflows.form.waitForData();
+
+    // Find and remove the claim set
+    const dataList = uiManagedWorkflows.form
+      .getFieldByLabel('Claim Sets')
+      .asDynamicDataListField().dataList;
+    const row = dataList.getRowByPropertyValue('key', args.claimSetUniqueKey);
+    try {
+      await row.getLocator().waitFor({ state: 'visible' });
+    } catch {
+      throw new Error('The claim set was not found on the subscription plan.');
+    }
+    await row.inlineMenu.openButton.click();
+    await row.inlineMenu.getActionByLabel('Unassign').click();
+    await dataList.waitForData();
+
+    // Back to subscription plan details
+    await uiShell.navigateToBreadcrumbPrevious();
+    await uiManagedWorkflows.form.waitForData();
+  }
+
+  /**
+   * This method sets subscription plan status and publishes the subscription plan.
+   * The management system must be loaded & signed in before using this method.
+   * If the subscription plan cannot be published then an exception will be raised.
+   *
+   * The following steps will be taken:
+   * - Navigate to the home breadcrumb, then tiles: 'Monetization', 'Subscription Plans'
+   * - Filter by title and click the subscription plan row action
+   * - Set the Status field
+   * - Click 'Publishing'
+   * - Click 'Publish' and confirm
+   * - Wait for the subscription plan details station to load and verify that the publication state is 'PUBLISHED'
+   */
+  async publishSubscriptionPlan(args: {
+    /** A unique subscription plan title. */
+    title: string;
+    /** The subscription plan status to be set. If omitted no change will be made. */
+    status?: 'Active' | 'Inactive';
+  }): Promise<void> {
+    const { uiShell, uiManagedWorkflows } = this;
+    await this.navigateToSubscriptionPlanDetails(args);
+
+    if (args.status !== undefined) {
+      await uiManagedWorkflows.form
+        .getFieldByName('isActive')
+        .asRadioField()
+        .setValue(args.status === 'Active' ? 'true' : 'false');
+    }
+
+    await uiShell.waitForPageTransition(
+      uiManagedWorkflows.actions.getActionByLabel('Publishing').click(),
+    );
+    await uiManagedWorkflows.form.waitForData();
+
+    const publishButton =
+      uiManagedWorkflows.actions.getActionByLabel('Publish');
+    try {
+      await publishButton.waitFor({ state: 'visible' });
+    } catch {
+      throw new Error(
+        'Subscription plan could not be published. Are there validation errors?',
+      );
+    }
+    await publishButton.click();
+    await uiManagedWorkflows.actions.confirmButton.click();
+    await uiManagedWorkflows.form.waitForData();
+  }
+
+  /**
+   * This method creates a new claim set.
+   * The management system must be loaded & signed in before using this method.
+   * When this method completes, the new claim set details station will be loaded.
+   *
+   * The following steps will be taken:
+   * - Navigate to the home breadcrumb, then tiles: 'Monetization', 'Claim Sets'
+   * - Click 'NEW', enter the title and key then click 'Proceed'
+   * - Wait for the claim set details station to load
+   */
+  async createClaimSet(properties: {
+    /** A unique subscription plan title. */
+    title: string;
+    /** The claim set unique key. */
+    uniqueKey: string;
+  }): Promise<void> {
+    const { uiShell, uiManagedWorkflows } = this;
+    await this.navigateToClaimSets();
+
+    await uiShell.waitForPageTransition(
+      uiManagedWorkflows.pageHeader.actions.getActionByLabel('NEW').click(),
+    );
+    await uiManagedWorkflows.form.waitForData();
+
+    await uiManagedWorkflows.form
+      .getFieldByName('title')
+      .asSingleLineTextField()
+      .setValue(properties.title);
+    await uiManagedWorkflows.form
+      .getFieldByName('key')
+      .asSingleLineTextField()
+      .setValue(properties.uniqueKey);
+    await uiShell.waitForPageTransition(
+      uiManagedWorkflows.actions.getActionByLabel(ActionLabel.Proceed).click(),
+    );
+    await uiManagedWorkflows.form.waitForData();
+  }
+
+  /**
+   * This method assigns claims to a claim set.
+   * The management system must be loaded & signed in before using this method.
+   * NOTE: This method does not support adding claims by mod*a*l.
+   *
+   * The following steps will be taken:
+   * - Navigate to the home breadcrumb, then tiles: 'Monetization', 'Claim Sets'
+   * - Filter by unique key and click the claim set row action
+   * - Click 'Claims'
+   * - Add each claim by checkbox or radio button
+   * - Click the 'previous' breadcrumb and wait for the claim set details station to load
+   */
+  async assignClaimsToClaimSet(args: {
+    /** The claim set unique key. */
+    uniqueKey: string;
+    /** The list of claim values to be assigned. Each claim input will be clicked. */
+    claims: string[];
+  }): Promise<void> {
+    const { uiShell, uiManagedWorkflows } = this;
+    await this.navigateToClaimSetDetails(args);
+
+    // Open claims editor
+    await uiShell.waitForPageTransition(
+      uiManagedWorkflows.actions.getActionByLabel('Claims').click(),
+    );
+
+    // Select each claim
+    const claimsEditor = new ClaimsEditor(this.page);
+    for (const claim of args.claims) {
+      const row = claimsEditor.getClaimRow(claim);
+      try {
+        await row.getLocator().waitFor({ state: 'visible' });
+      } catch (e) {
+        throw new Error(
+          `A radio or checkbox for for claim '${claim}' is not visible. NOTE: selecting claims by mod*a*l is not supported by this method.` +
+            (e instanceof Error ? `\n${e.message}` : ''),
+        );
+      }
+      await row.toggle();
+    }
+    // Back to claim set details
+    await uiShell.navigateToBreadcrumbPrevious();
+    await uiManagedWorkflows.form.waitForData();
+  }
+
+  /**
+   * This method assigns claims to a claim set.
+   * The management system must be loaded & signed in before using this method.
+   * NOTE: This method *does* support adding claims by mod*a*l.
+   *
+   * The following steps will be taken:
+   * - Navigate to the home breadcrumb, then tiles: 'Monetization', 'Claim Sets'
+   * - Filter by unique key and click the claim set row action
+   * - Click 'Claims'
+   * - Add each claim by checkbox or radio button
+   * - Click the 'previous' breadcrumb and wait for the claim set details station to load
+   */
+  async assignClaimsToClaimSetByLabel(args: {
+    /** The claim set unique key. */
+    uniqueKey: string;
+    /** The label of the claim group. */
+    claimGroupLabel: string;
+    /** The claim labels in the claim group. Each will be clicked or added by modal as required. */
+    claimLabels: string[];
+  }): Promise<void> {
+    const { uiShell, uiManagedWorkflows } = this;
+    await this.navigateToClaimSetDetails(args);
+
+    // Open claims editor
+    await uiShell.waitForPageTransition(
+      uiManagedWorkflows.actions.getActionByLabel('Claims').click(),
+    );
+
+    // Select each claim
+    const claimsEditor = new ClaimsEditor(this.page);
+    const group = claimsEditor.getClaimGroup(args.claimGroupLabel);
+    try {
+      await group.row.waitFor({ state: 'visible' });
+    } catch (e) {
+      throw new Error(
+        `A claim group with label ${args.claimGroupLabel} is not visible.` +
+          (e instanceof Error ? `\n${e.message}` : ''),
+      );
+    }
+    await group.expand();
+    if (await group.isDataListEntry()) {
+      // Select each claim with selection explorer
+      const modal = group.explorerModal;
+      for (const claimLabel of args.claimLabels) {
+        await group.dataList.dataEntryRow.addButton.click();
+        await modal.waitToOpen();
+        await modal.list.waitForData();
+
+        // filter to the claim
+        await modal.filters
+          .getFilterByName('title')
+          .asFreeTextFilter()
+          .setValue(claimLabel);
+        await modal.list.waitForData();
+        if ((await modal.list.allVisibleRows.count()) !== 1) {
+          throw new Error(
+            `A entry for claim with label '${claimLabel}' is not visible in the modal for group '${args.claimGroupLabel}'.`,
+          );
+        }
+
+        // assign the claim
+        await modal.list.getRow(1).selectButton.click();
+        await modal.waitToClose();
+      }
+    } else {
+      // Select each claim
+      for (const claimLabel of args.claimLabels) {
+        const row = group.getClaimRowByLabel(claimLabel);
+        try {
+          await row.getLocator().waitFor({ state: 'visible' });
+        } catch (e) {
+          throw new Error(
+            `A radio or checkbox for claim with label '${claimLabel}' is not visible in group '${args.claimGroupLabel}'.` +
+              (e instanceof Error ? `\n${e.message}` : ''),
+          );
+        }
+        await row.toggle();
+      }
+    }
+    // Back to claim set details
+    await uiShell.navigateToBreadcrumbPrevious();
+    await uiManagedWorkflows.form.waitForData();
+  }
+
+  /**
+   * This method publishes a claim set.
+   * The management system must be loaded & signed in before using this method.
+   * If the claim set cannot be published then an exception will be raised.
+   *
+   * The following steps will be taken:
+   * - Navigate to the home breadcrumb, then tiles: 'Monetization', 'Claim Sets'
+   * - Filter by unique key and click the claim set row action
+   * - Click 'Publishing'
+   * - Click 'Publish' and confirm
+   * - Wait for the claim set details station to load
+   */
+  async publishClaimSet(args: {
+    /** The claim set unique key. */
+    uniqueKey: string;
+  }): Promise<void> {
+    const { uiShell, uiManagedWorkflows } = this;
+    await this.navigateToClaimSetDetails(args);
+
+    await uiShell.waitForPageTransition(
+      uiManagedWorkflows.actions.getActionByLabel('Publishing').click(),
+    );
+    await uiManagedWorkflows.form.waitForData();
+
+    const action = uiManagedWorkflows.actions.getActionByLabel('Publish');
+    try {
+      await action.waitFor({ state: 'visible' });
+    } catch {
+      throw new Error(
+        'Claim set could not be published. Are there validation errors?',
+      );
+    }
+    await action.click();
+    await uiShell.waitForPageTransition(
+      uiManagedWorkflows.actions.confirmButton.click(),
+    );
+    await uiManagedWorkflows.form.waitForData();
+  }
+
+  /**
+   * This method unpublishes a claim set by unique key.
+   * The management system must be loaded & signed in before using this method.
+   * If the claim set cannot be unpublished then an exception will be raised.
+   *
+   * The following steps will be taken:
+   * - Navigate to the home breadcrumb, then tiles: 'Monetization', 'Claim Sets'
+   * - Filter by unique key and click the claim set row action
+   * - Click 'Unpublish' and confirm
+   * - Wait for the claim sets details station to load
+   */
+  async unpublishClaimSet(args: { uniqueKey: string }): Promise<void> {
+    const { uiShell, uiManagedWorkflows } = this;
+    await this.navigateToClaimSetDetails(args);
+
+    const action = uiManagedWorkflows.actions.getActionByLabel('Unpublish');
+    try {
+      await action.waitFor({ state: 'visible' });
+    } catch {
+      throw new Error('The "Unpublish" action is not visible.');
+    }
+    await action.click();
+    await uiShell.waitForPageTransition(
+      uiManagedWorkflows.actions.confirmButton.click(),
+    );
+    await uiManagedWorkflows.form.waitForData();
+  }
+
+  /**
+   * This method deletes a claim set by unique key.
+   * The management system must be loaded & signed in before using this method.
+   * If the claim set cannot be deleted then an exception will be raised.
+   *
+   * The following steps will be taken:
+   * - Navigate to the home breadcrumb, then tiles: 'Monetization', 'Claim Sets'
+   * - Filter by unique key and click the claim set row action
+   * - Click 'Delete' and confirm
+   * - Wait for the claim sets explorer to load
+   */
+  async deleteClaimSet(args: {
+    /** The claim set unique key. */
+    uniqueKey: string;
+  }): Promise<void> {
+    const { uiShell, uiManagedWorkflows } = this;
+    await this.navigateToClaimSetDetails(args);
+
+    // Delete the claim set
+    const action = uiManagedWorkflows.actions.getActionByLabel('Delete');
+    try {
+      await action.waitFor({ state: 'visible' });
+    } catch {
+      throw new Error('The "Delete" action is not visible.');
+    }
+    await action.click();
+    await uiShell.waitForPageTransition(
+      uiManagedWorkflows.actions.confirmButton.click(),
+    );
+    await uiManagedWorkflows.list.waitForData();
+  }
+}

package/src/managed-services/monetization-service/payment-plan-recurrence-period-field.ts

@@ -0,0 +1,43 @@
+import { GenericField } from '@axinom/mosaic-e2e-ui-selectors';
+
+/**
+ * A model for a "Recurrence Period" form field which can be used to configure
+ * the "Recurrence Period" field on payment plans. This is a custom FormField component.
+ *
+ * It is advised not to use this model directly but to use fixed pre-configured
+ * subscription plans for end-to-end testing of payment provider integrations.
+ *
+ * Example usage:
+ * ```
+ * await uiManagedWorkflows.form
+ * .getFieldByLabel('Recurrence Period')
+ * .as(PaymentPlanRecurrencePeriodField)
+ * .setValues(1, 'WEEK');
+ * ```
+ */
+export class PaymentPlanRecurrencePeriodField extends GenericField {
+  /** @inheritdoc */
+  protected override get fieldTypeValidator(): string {
+    return '[@data-test-type="PaymentProviderRecurrencePeriod"]';
+  }
+
+  readonly quantityInput = this.content.locator(
+    '//input[@name="periodQuantity"]',
+  );
+  readonly unitInput = this.content.locator('//select[@name="periodUnit"]');
+
+  /**
+   * Sets values for both inputs of the recurrence period field.
+   *
+   * @param quantity  Value for the number entry input
+   * @param unit  The dropdown label to select
+   */
+  async setValues(
+    quantity: number,
+    unit: 'day(s)' | 'week(s)' | 'month(s)' | 'year(s)',
+  ): Promise<void> {
+    await this.verifyFieldType();
+    await this.quantityInput.fill(quantity.toString());
+    await this.unitInput.selectOption({ label: unit });
+  }
+}

package/src/managed-services/monetization-service/payment-provider-settings-field.ts

@@ -0,0 +1,76 @@
+import { GenericField } from '@axinom/mosaic-e2e-ui-selectors';
+
+/** A model for a payment provider settings form field which can
+ * be used to configure payment provider settings on subscription plans and
+ * payment plans. This is a custom FormField component.
+ *
+ * It is advised not to use this model directly but to use fixed pre-configured
+ * subscription plans for end-to-end testing of payment provider integrations.
+ *
+ * Example usage:
+ * ```
+ * const field = uiManagedWorkflows.form
+ *  .getFieldByLabel('Payment Providers & Settings')
+ *  .as(PaymentProviderSettingsField);
+ * await field.addPaymentProvider('PAYPAL');
+ * await field.setExternalId('PAYPAL', 'P-123XYZ');
+ * ```
+ */
+export class PaymentProviderSettingsField extends GenericField {
+  /** @inheritdoc */
+  protected override get fieldTypeValidator(): string {
+    return '[@data-test-type="SubscriptionPlanProviderConfigs" or @data-test-type="PaymentPlanProviderConfigs"]';
+  }
+
+  /**
+   * Add a payment provider.
+   *
+   * @param paymentProviderTitle Label for the payment provider. e.g. 'PayPal'
+   */
+  async addPaymentProvider(paymentProviderTitle: string): Promise<void> {
+    const providerSelect = this.getLocator(
+      '//*[@data-test-id="payment-provider-selection-row"]//select',
+    );
+    const providerAddButton = this.getLocator(
+      '//*[@data-test-id="payment-provider-selection-row"]//button',
+    );
+
+    await this.verifyFieldType();
+    try {
+      await providerSelect
+        .locator(`//option[text()="${paymentProviderTitle}"]`)
+        .waitFor({ state: 'attached' });
+    } catch {
+      throw new Error(
+        `Could not add payment provider '${paymentProviderTitle}'. Is the payment provider enabled for this environment and not already added to this plan?`,
+      );
+    }
+    await providerSelect.selectOption({ label: paymentProviderTitle });
+    await providerAddButton.click();
+  }
+
+  /**
+   * Set the external ID of an added payment provider.
+   *
+   * @param paymentProviderTitle Label for the payment provider. e.g. 'PayPal'
+   * @param externalId A value to set as the external Id.
+   */
+  async setExternalId(
+    paymentProviderTitle: string,
+    externalId: string,
+  ): Promise<void> {
+    const input = this.getLocator(
+      `//*[@data-test-id="payment-provider-config:${paymentProviderTitle}"]//input[contains(@name, "externalId")]`,
+    );
+
+    await this.verifyFieldType();
+    try {
+      await input.waitFor({ state: 'visible' });
+    } catch {
+      throw new Error(
+        `Could not set 'externalId' for payment provider '${paymentProviderTitle}'. Is the payment provider enabled and not published for this plan?`,
+      );
+    }
+    await input.fill(externalId);
+  }
+}