Should we switch to a builder API for creating interactors?

[jnicklas]

When working on folio, we ran into situations where we wanted to extend existing interactors. This proved to be not easy. While working with this, I discovered an alternative API for creating interactors, which has some advantages over the current API. This API uses a builder pattern, similar to our test suite DSL. All of the concepts are the same, there is only a slight syntactic difference:

To compare, the current API looks like this:

createInteractor<HTMLLinkElement>('link')({
  selector: 'a',
  actions: {
    click: perform(element => { element.click() }),
    setHref: perform((element, value: string) => { element.href = value })
  },
  filters: {
    title: (element) => element.title,
    href: (element) => element.href,
    id: (element) => element.id,
    visible: {
      apply: (element) => element.clientHeight > 0,
      default: true
    },
  }
});

The new API could look like this:

createInteractor<HTMLLinkElement>('link')
  .selector('a')
  .actions({
    click: perform(element => { element.click() }),
    setHref: perform((element, value: string) => { element.href = value })
  })
  .filters({
    title: (element) => element.title,
    href: (element) => element.href,
    id: (element) => element.id,
    visible: {
      apply: (element) => element.clientHeight > 0,
      default: true
    },
  });

Or we could take the opportunity to simplify action definition:

createInteractor<HTMLLinkElement>('link')
  .selector('a')
  .actions('click', element => { element.click() })

And then we could add a more general define which would work for composite actions, as well as assertions:

createInteractor<HTMLElement>('datepicker')
  .selector('.datepicker')
  .define('open', (interactor) => interactor.find(Link('open')).click())
  .define('hasClass, (interactor, value: string) => interactor.assert((e) => e.classList.contains(value)))

Interestingly, I think it is possible to implement this API backwards compatibly! However, there are some slight disadvantages to implementing this with backwards compatibility, which lead me to think that we should deprecate the existing API.

Advantages

There are two main advantages to this API:

Easier extensions

A challenge with interactors right now is that we ship some built in interactors, but extending them is difficult. This new API makes it very straight-forward!

import { Button as ButtonInteractor } from 'bigtest';

export const Button = ButtonInteractor.filter('myFilter', (e) => ...);

There is no special API for extending interactors, it's just the normal flow, and each intermediate step is itself extensible.

Self references

In an action, it is currently not possible to reference another action or filter on the interactor passed to the function as an argument (in TypeScript, this is purely a type issue), the builder API makes it possible to define to previously defined actions and filters

Challenges

A desirable feature would be to have a method to narrow the type of element. For example, we could create a base interactor for all HTMLElement interactors which implements the id and title filters, and then use this as a starting point for other interactors:

let baseInteractor = createInteractor<HTMLElement>('html')
   .filter('id', (el) => el.id))

let linkInteractor = baseInteractor.extend<HTMLLinkElement>('link')

On the surface, this seems like it should work, but we once again run into issues of variance. The types of actions and filters Actions<E> and Filters<E> end up with a contravariant type parameter E, and so we cannot substitute a Actions<HTMLLinkElement> for a Actions<HTMLElement>. I think this is solvable, but it will definitely require backwards-incompatible changes to the types. Basically we should stop carrying forward the types of the action definitions, and instead carry forward the types of their implementations. These are not parameterized over the element type, and so will not run into this problem.

I've added a partial implementation here: #735

[jorgelainfiesta]

From a learning perspective, I'd argue that it's better to have BigTest users only use one paradigm to write BigTest, so this is great!

I'm just not too sure about the generic define, will people end up creating chaotic/confusing Interactors with that?

Also, as we approach a more public release I think that all API change discussions should consider as well how we migrate from what we have. Can we create a codemod that works for most cases? or will it be a painful task for everyone to upgrade to the new API? At Folio, for instance, how much work do we need to put to migrate all the Interactors to a new syntax?

[cowboyd]

I think a codemod would definitely be doable, but probably overkill at this point since we are all directly connected to all of the codebases that currently use interactors.

I'm just not too sure about the generic define, will people end up creating chaotic/confusing Interactors with that?

Yeah, feels a bit to abstract. Perhaps we could make define an external function since it would really only be used by folks doing acrobatics with interactors?

[minkimcello]

Yeah this is what I was trying to ask in our discord channel. Would there be any benefits to using define as opposed to just creating filters and actions on their own? @jnicklas

But the API change itself in the writing syntax, if that helps unblock a technical issue that allows users to more easily extend interactors, I think we should do it before we release the docs.

[jbolda]

I suspect, as far as messaging goes, something generic for interactor aerobatics isn't the worst idea. We could specifically document it as something only to be used if you are doing something really tricky / non-standard. It speaks to me a bit like the unsafe flag in Rust. If it is one standard term, you could search a codebase to see where it comes up and then point towards some interest to try to refactor anything that uses it if possible.

[jorgelainfiesta]

Min has a great point, it'd be best to ship the docs with the new API. It'd be a bad experience if they start trying things out and then we change entirely everything they've done. They'll just abandon the project at that point.

[jorgelainfiesta]

The new API allows more flexibility for people to write things. Is it valid to invoke a method multiple times? For instance, if I apply actions several times will they merge or what's the expectation?

I made a little example to see if I get it:

let linkInteractor = createInteractor<HTMLLinkElement>('link')
  .selector('a')
  .actions({
    click: perform(element => { element.click() })
  })
  .filters({
    title: (element) => element.title,
    href: (element) => element.href,
    id: (element) => element.id,
    visible: {
      apply: (element) => element.clientHeight > 0,
      default: true
    },
  })
  .actions({
    hover: perform((element) => { element.hover() }) // don't know how to do this actually
  })
 
let navlinkInteractor = linkInteractor
  .selector('.nav-link')
  .filter({
    active: (element) => element.attr['aria-active-link'] 
  })

If that's correct, would it be valid to say:

export default test('BigTest')
  .step(
    Page.visit('/'),
    NavlinkInteractor('About').click())
  .assertion(NavlinkInteractor('About').is('active'));

[cowboyd]

@jorgelainfiesta you’re pretty much spot on as I understand it. Newer actions would be merged in with older ones