In testcafe, can you create a custom test action that chains custom calls until it returns a TestControllerPromise?

Here's how I'd like my testcafe custom test action to look:

  await t
    .click(Selector(/* ... */))
    .customActions
      .toFindOneDialogElement() // returns my code
      .withExactTitle("My Title") // returns my code
      .and() // returns my code
      .withExactBodyText("My content") // returns my code
      .done() // returns TestControllerPromise
    .click(Selector(/* ... */))

The documentation says:

> If you want to include custom actions in action chains, make sure the function does not return a value.

But in my API, I want to return a custom value until done is called. Can this be done?

Here is my attempt. I'll start with the type definitions:

import "testcafe";

declare global {
  interface CustomActions {
    toFindOneDialogElement: () => Promise<BuilderMatcher & BuilderDone>;
  }
}

interface BuilderMatcher {
  withExactTitle: (
    exactTitle: string
  ) => Promise<BuildMatcherBooleanOperator & BuilderDone>;
  withExactBodyText: (
    exactBodyText: string
  ) => Promise<BuildMatcherBooleanOperator & BuilderDone>;
}

interface BuildMatcherBooleanOperator {
  and: () => Promise<BuilderMatcher>;
}

interface BuilderDone {
  done: () => TestControllerPromise;
}

Here is my implementation inside the .testcaferc "customActions" property:

{
  async toFindOneDialogElement() {
    const self = this;
    let exactTitle = undefined;
    let exactBodyText = undefined;

    async function done() {
      exactTitle !== undefined &&
        (await self.expect(Selector("...").innerText).eql(exactTitle));

      exactBodyText !== undefined &&
        (await self.expect(Selector(`...`).innerText).eql(exactBodyText));

      return self;
    }

    async function and() {
      return builderMatcher;
    }

    const builderMatcher = {
      withExactTitle: async function (exactTitleParam) {
        exactTitle = exactTitleParam;
        return { done, and };
      },
      withExactBodyText: async function (exactBodyTextParam) {
        exactBodyText = exactBodyTextParam;
        return { done, and };
      },
      done,
    };

    return builderMatcher;
  },
}

When I try to use my custom test action like the first code sample, it does not compile because that first function returns a Promise<T> and must be awaited. The fix is straightforward but it ruins the API design: it no longer chains.

The built-in testcafe actions can chain without awaiting each call. Is there a way my custom action API can too?

Your current implementation works as expected in terms of JavaScript. We are awaiting the custom action async function to be finished. If this function returns some value, we will return this value as a result of this function call. So the function return type is Promise<value>. If no value has been returned, we will return TestControllerPromise object which is our custom object that has all the TestCafe actions. That is why you cannot chain your code this way. Currently, you can change your chain as follows:

 await t.customActions
        .toFindOneDialogElement()
        .then(builder => builder.withExactTitle('More information...'))
        .then(builder => builder.and())
        .then(builder => builder.withExactBodyText('More information...'))
        .then(builder => builder.done())

Also, you need to update your selectors since they are not able to get a bound testRun in this case:

Selector('...').with({ boundTestRun: self }).innerText

But in this case, the built-in chain after the toFindOneDialogElement call will be lost. If you would like internal TestCafe logic to make these methods chainable, you need to put them in separate actions and call them through the customActions property as follows:

 await t
        .click('...')
        .customActions.toFindOneDialogElement()
        .customActions.withExactTitle('More information...')
        .customActions.and()
        .customActions.withExactBodyText('More information...')
        .customActions.done()
        .click('...')