import {List} from '@serenity-js/core/lib/screenplay/questions'
public class | source

List

Filters an Answerable list of items based on the criteria provided. Instantiate via List.of

Extends:

Question → List

Examples:

Example data structure
 interface TestAccount {
     username: string;
     role: string;
     environments: string[];
 }

 const testAccounts: TestAccount[] = [
     {
         "username": "tester.one@example.com",
         "role": "test-automation"
         "environments": [ "dev", "sit" ],
     },
     {
         "username": "tester.two@example.com",
         "role": "test-automation"
         "environments": [ "dev", "sit", "prod" ],
     },
     {
         "username": "release.bot@example.com",
         "role": "release-automation"
         "environments": [ "dev", "sit", "prod" ],
     }
 ]
Using with Property
 import { actorCalled, List, Property } from '@serenity-js/core';
 import { contain, Ensure, equals } from '@serenity-js/assertions';

 actorCalled('Lisa').attemptsTo(
     Ensure.that(
         Property.of(
             List.of(testAccounts)
                 .where(Property.at<TestAccount>().environments, contain('prod'))
                 .where(Property.at<TestAccount>().role, equals('test-automation'))
                 .first()
             ).username,
         equals('tester.two@example.com')
     )
 )

See also:

Static Method Summary

Static Public Methods
public static

of(items: Answerable<Item_Type[]>): List<ArrayListAdapter<Item_Type>, Item_Type, Item_Type[], Promise<Item_Type>, Promise<Item_Type[]>>

Instantiates a new List configured to support standard Array.

Constructor Summary

Public Constructor
public

constructor(collection: List_Adapter_Type)

Method Summary

Public Methods
public

answeredBy(actor: AnswersQuestions & UsesAbilities): Collection_Return_Type

Makes the provided Actor answer this Question and return the underlying collection.

public

count(): Question<Promise<number>>

Returns the number of items left after applying any filters,

public

first(): Question<Item_Return_Type>

Returns the first of items left after applying any filters,

public

get(index: number): Question<Item_Return_Type>

Returns the nth of the items left after applying any filters,

public

last(): Question<Item_Return_Type>

Returns the last of items left after applying any filters,

public

where(question: MetaQuestion<Item_Type, Promise<Answer_Type>|Answer_Type>, expectation: Expectation<any, Answer_Type>): List<List_Adapter_Type, Item_Type, Collection_Type, Item_Return_Type, Collection_Return_Type>

Filters the underlying collection so that the result contains only those elements that meet the Expectation

Inherited Summary

From class Question
public static

about(description: string, body: function(actor: AnswersQuestions & UsesAbilities): R): Question<R>

Factory method that simplifies the process of defining custom questions.

public static

isAQuestion(maybeQuestion: any): boolean

Checks if the value is a Question.

public

subject: *

public

describedAs(subject: string): Question<T>

Changes the description of this question's subject.

public

map(mapping: function(value: A, index?: number): Promise<O> | O): Question<Promise<Mapped>>

Creates a new Question, which value is a result of applying the mapping function to the value of this Question.

public

toString(): string

Describes the subject of this Question.

Static Public Methods

public static of(items: Answerable<Item_Type[]>): List<ArrayListAdapter<Item_Type>, Item_Type, Item_Type[], Promise<Item_Type>, Promise<Item_Type[]>> source

Instantiates a new List configured to support standard Array.

Please note: Don't use List.of to wrap Question<ElementArrayFinder> returned by Target.all. Instead, use Target.all(...).located(...).where(...), which uses a Protractor-specific ListAdapter.

Params:

NameTypeAttributeDescription
items Answerable<Item_Type[]>

Returns:

List<ArrayListAdapter<Item_Type>, Item_Type, Item_Type[], Promise<Item_Type>, Promise<Item_Type[]>>

Public Constructors

public constructor(collection: List_Adapter_Type) source

Params:

NameTypeAttributeDescription
collection List_Adapter_Type

Public Methods

public answeredBy(actor: AnswersQuestions & UsesAbilities): Collection_Return_Type source

Makes the provided Actor answer this Question and return the underlying collection.

Params:

NameTypeAttributeDescription
actor AnswersQuestions & UsesAbilities

Returns:

Collection_Return_Type

public count(): Question<Promise<number>> source

Returns the number of items left after applying any filters,

Returns:

Question<Promise<number>>

Examples:

Counting items
 import { actorCalled, List } from '@serenity-js/core';
 import { Ensure, equals, property } from '@serenity-js/assertions';

 actorCalled('Lisa').attemptsTo(
     Ensure.that(
         List.of(testAccounts).count(),
         equals(3)
     )
 )

public first(): Question<Item_Return_Type> source

Returns the first of items left after applying any filters,

Returns:

Question<Item_Return_Type>

Examples:

Retrieving the first item
 import { actorCalled, List } from '@serenity-js/core';
 import { Ensure, equals, property } from '@serenity-js/assertions';

 actorCalled('Lisa').attemptsTo(
     Ensure.that(
         List.of(testAccounts).first(),
         property('username', equals('tester.one@example.com'))
     )
 )

public get(index: number): Question<Item_Return_Type> source

Returns the nth of the items left after applying any filters,

Params:

NameTypeAttributeDescription
index number

Zero-based index of the item to return

Returns:

Question<Item_Return_Type>

Examples:

Retrieving the nth item
 import { actorCalled, List } from '@serenity-js/core';
 import { Ensure, equals, property } from '@serenity-js/assertions';

 actorCalled('Lisa').attemptsTo(
     Ensure.that(
         List.of(testAccounts).get(1),
         property('username', equals('tester.two@example.com'))
     )
 )

public last(): Question<Item_Return_Type> source

Returns the last of items left after applying any filters,

Returns:

Question<Item_Return_Type>

Examples:

Retrieving the last item
 import { actorCalled, List } from '@serenity-js/core';
 import { Ensure, equals, property } from '@serenity-js/assertions';

 actorCalled('Lisa').attemptsTo(
     Ensure.that(
         List.of(testAccounts).last(),
         property('username', equals('release.bot@example.com'))
     )
 )

public where(question: MetaQuestion<Item_Type, Promise<Answer_Type>|Answer_Type>, expectation: Expectation<any, Answer_Type>): List<List_Adapter_Type, Item_Type, Collection_Type, Item_Return_Type, Collection_Return_Type> source

Filters the underlying collection so that the result contains only those elements that meet the Expectation

Params:

NameTypeAttributeDescription
question MetaQuestion<Item_Type, Promise<Answer_Type>|Answer_Type>
expectation Expectation<any, Answer_Type>

Returns:

List<List_Adapter_Type, Item_Type, Collection_Type, Item_Return_Type, Collection_Return_Type>

Examples:

Filtering a list
 import { actorCalled, List, Property } from '@serenity-js/core';
 import { contain, Ensure, equals, property } from '@serenity-js/assertions';

 actorCalled('Lisa').attemptsTo(
     Ensure.that(
         List.of(testAccounts)
             .where(Property.at<TestAccount>().environments, contain('prod'))
             .where(Property.at<TestAccount>().role, equals('test-automation'))
             .first(),
         property('username', equals('tester.two@example.com'))
     )
 )