Support `.where` filters in Serenity/JS 3.0.0

As per my conversation with @viper3400 on Serenity/JS Community Chat

const Dialogs = Target.all('visible modal dialogs').located(by.css('.ui-dialog'));
const DialogTitle = Target.the('dialog title').located(by.css('.ui-dialog-title'));
const DialogWithTitle = (title: string) => 
  Dialogs.where(Text.of(DialogTitle), includes(title)).first();

Serenity/JS 3.0 should support Screenplay-style .where filters for nested page elements.

[viper3400]

At the moment we have a common library + 2 project libraries. By now I just migrated the common library which has just some basic tests, but the .where looks good so far. Thanks!

This is just a first feedback, as I’m not sure, when I can try a migration of one of the main projects (and they contain much more code).

[jan-molak]

This feature will land in 3.0.0-rc.3, with a new implementation of List supporting both the regular Arrays and PageElements.

For example:

        const items = [ 1, 2, 3, 4, 5 ];

        const list = List.of(items);

        const result = await list
            .where(Value, isGreaterThan(2))
            .where(Value, isLessThan(5))
            .answeredBy(actor)
        
        // [ 3, 4 ]

where:

class Value {
    static of<T>(item: T): Question<Promise<T>> {
        return Question.about('some value', actor => Promise.resolve(item));
    }
}

Another API worth mentioning is List.eachMappedTo:

        const accounts: Account[] = [
            { id: 1, name: 'Alice' },
            { id: 2, name: 'Arbnor' },
            { id: 3, name: 'Bob' },
        ];

        const list = List.of(accounts);

        const result = await list
            .where(AccountName, startsWith('A'))
            .eachMappedTo(AccountName)
            .answeredBy(actor);

        // ['Alice', 'Arbnor']

where:

class AccountName {
    static of = (account: Account) =>
        Question.about('account name', actor => account.name)
}

I will also remove filter and map methods from PageElements since they have proven to provide little value without the actor being readily available.