@serenity-js/assertions 3.0.0-rc.9 → 3.0.0

package/src/expectations/containItemsWhereEachItem.ts

@@ -1,5 +1,26 @@
-import { Answerable, AnswersQuestions, d, Expectation, ExpectationMet, ExpectationNotMet, ExpectationOutcome } from '@serenity-js/core';
+import { Answerable, AnswersQuestions, d, Expectation, ExpectationDetails, ExpectationMet, ExpectationNotMet, ExpectationOutcome, Unanswered } from '@serenity-js/core';
 
+/**
+ * Produces an {@apilink Expectation|expectation} that is met when all the items of the actual array of `Item[]`
+ * meet the `expectation`.
+ *
+ * ## Ensuring that all the items in an array meet the expectation
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, containItemsWhereEachItem, endsWith } from '@serenity-js/assertions'
+ *
+ * const items = [ 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday' ]
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that(items, containItemsWhereEachItem(endsWith('day'))),
+ * )
+ * ```
+ *
+ * @param expectation
+ *
+ * @group Expectations
+ */
 export function containItemsWhereEachItem<Actual>(expectation: Expectation<Actual>): Expectation<Actual[]> {
     return new ContainItemsWhereEachItemMeetsExpectation(expectation);
 }
@@ -15,20 +36,23 @@ class ContainItemsWhereEachItemMeetsExpectation<Actual> extends Expectation<Actu
 
     constructor(private readonly expectation: Expectation<Actual>) {
         super(
+            'containItemsWhereEachItem',
             ContainItemsWhereEachItemMeetsExpectation.descriptionFor(expectation),
             async (actor: AnswersQuestions, actual: Answerable<Actual[]>) => {
 
                 const items: Actual[] = await actor.answer(actual);
 
                 if (! items || items.length === 0) {
+                    const unanswered = new Unanswered();
                     return new ExpectationNotMet(
                         ContainItemsWhereEachItemMeetsExpectation.descriptionFor(expectation),
-                        undefined,
+                        ExpectationDetails.of('containItemsWhereEachItem', unanswered),
+                        unanswered,
                         items,
                     );
                 }
 
-                let outcome: ExpectationOutcome<unknown, Actual>;
+                let outcome: ExpectationOutcome;
 
                 for (const item of items) {
 
@@ -37,13 +61,19 @@ class ContainItemsWhereEachItemMeetsExpectation<Actual> extends Expectation<Actu
                     if (outcome instanceof ExpectationNotMet) {
                         return new ExpectationNotMet(
                             ContainItemsWhereEachItemMeetsExpectation.descriptionFor(expectation),
+                            ExpectationDetails.of('containItemsWhereEachItem', outcome.expectation),
                             outcome.expected,
-                            items
+                            items,
                         );
                     }
                 }
 
-                return new ExpectationMet(ContainItemsWhereEachItemMeetsExpectation.descriptionFor(expectation), outcome.expected, items);
+                return new ExpectationMet(
+                    ContainItemsWhereEachItemMeetsExpectation.descriptionFor(expectation),
+                    ExpectationDetails.of('containItemsWhereEachItem', outcome.expectation),
+                    outcome.expected,
+                    items,
+                );
             }
         );
     }

package/src/expectations/endsWith.ts

@@ -1,6 +1,26 @@
-import { Answerable, Expectation } from '@serenity-js/core';
+import { Expectation } from '@serenity-js/core';
 
-export function endsWith(expected: Answerable<string>): Expectation<string> {
-    return Expectation.thatActualShould<string, string>('end with', expected)
-        .soThat((actualValue, expectedValue) => actualValue.endsWith(expectedValue));
-}
+/**
+ * Creates an {@apilink Expectation|expectation} that is met when the actual `string` value
+ * ends with the resolved value of `expected`.
+ *
+ * ## Ensuring that a given string ends with an expected substring
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, endsWith } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that('Hello World!', endsWith('!')),
+ * )
+ * ```
+ *
+ * @param expected
+ *
+ * @group Expectations
+ */
+export const endsWith = Expectation.define(
+    'endsWith', 'end with',
+    (actual: string, expected: string) =>
+        actual.endsWith(expected)
+)

package/src/expectations/equals.ts

@@ -1,7 +1,33 @@
-import { Answerable, Expectation } from '@serenity-js/core';
+import { Expectation } from '@serenity-js/core';
 import { equal } from 'tiny-types/lib/objects';
 
-export function equals<Expected>(expectedValue: Answerable<Expected>): Expectation<Expected> {
-    return Expectation.thatActualShould<Expected, Expected>('equal', expectedValue)
-        .soThat((actual, expected) => equal(actual, expected));
-}
+/**
+ * Produces an {@apilink Expectation|expectation} that is met when the actual value
+ * is equal to the resolved value of `expectedValue`.
+ *
+ * Note that the equality check performs comparison **by value**
+ * using [TinyTypes `equal`](https://github.com/jan-molak/tiny-types/blob/master/src/objects/equal.ts).
+ *
+ * ## Ensuring that the actual value equals expected value
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ *
+ * const actual   = { name: 'apples' }
+ * const expected = { name: 'apples' }
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that(actual, equals(expected)),
+ * )
+ * ```
+ *
+ * @param expectedValue
+ *
+ * @group Expectations
+ */
+export const equals = Expectation.define(
+    'equals', 'equal',
+    <T>(actual: T, expected: T) =>
+        equal(actual, expected),
+);

package/src/expectations/includes.ts

@@ -1,6 +1,26 @@
-import { Answerable, Expectation } from '@serenity-js/core';
+import { Expectation } from '@serenity-js/core';
 
-export function includes(expected: Answerable<string>): Expectation<string> {
-    return Expectation.thatActualShould<string, string>('include', expected)
-        .soThat((actualValue, expectedValue) => actualValue.includes(expectedValue));
-}
+/**
+ * Creates an {@apilink Expectation|expectation} that is met when the actual `string` value
+ * includes a substring of `expected`.
+ *
+ * ## Ensuring that a given string includes the expected substring
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, includes } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that('Hello World!', includes('World')),
+ * )
+ * ```
+ *
+ * @param expected
+ *
+ * @group Expectations
+ */
+export const includes = Expectation.define(
+    'includes', 'include',
+    (actual: string, expected: string) =>
+        actual.includes(expected)
+);

package/src/expectations/index.ts

@@ -7,6 +7,7 @@ export * from './equals';
 export * from './includes';
 export * from './isAfter';
 export * from './isBefore';
+export * from './isCloseTo';
 export * from './isFalse';
 export * from './isGreaterThan';
 export * from './isLessThan';
@@ -15,4 +16,5 @@ export * from './isTrue';
 export * from './matches';
 export * from './not';
 export * from './or';
+export * from './property';
 export * from './startsWith';

package/src/expectations/isAfter.ts

@@ -1,6 +1,46 @@
-import { Answerable, Expectation } from '@serenity-js/core';
+import { Expectation } from '@serenity-js/core';
 
-export function isAfter(expected: Answerable<Date>): Expectation<Date> {
-    return Expectation.thatActualShould<Date, Date>('have value that is after', expected)
-        .soThat((actualValue, expectedValue) => actualValue.getTime() > expectedValue.getTime());
-}
+/**
+ * Creates an {@apilink Expectation|expectation} that is met when the actual value of type `Date`
+ * is after the expected `Date`.
+ *
+ * ## Ensuring that a given date is after the expected date
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, isAfter } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that(new Date('2022-01-01'), isAfter(new Date('1995-01-01'))),
+ * )
+ * ```
+ *
+ * ## Ensuring that a given date is within the expected date range
+ *
+ * ```ts
+ * import { actorCalled, Expectation, d } from '@serenity-js/core'
+ * import { Ensure, and, isAfter, isBefore } from '@serenity-js/assertions'
+ *
+ * const isWithinDateRange = (lowerBound: Answerable<Date>, upperBound: Answerable<Date>) =>
+ *   Expectation.to(d`have value that is between ${ lowerBound } and ${ upperBound }`)
+ *     .soThatActual(
+ *       and(isAfter(lowerBound), isBefore(upperBound))
+ *     ),
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that(
+ *     new Date('2022-01-01'),
+ *     isWithinDateRange(new Date('1995-01-01'), new Date('2025-01-01'))
+ *   ),
+ * )
+ * ```
+ *
+ * @param expected
+ *
+ * @group Expectations
+ */
+export const isAfter = Expectation.define(
+    'isAfter', 'have value that is after',
+    (actual: Date, expected: Date) =>
+        actual.getTime() > expected.getTime()
+);

package/src/expectations/isBefore.ts

@@ -1,6 +1,46 @@
-import { Answerable, Expectation } from '@serenity-js/core';
+import { Expectation } from '@serenity-js/core';
 
-export function isBefore(expected: Answerable<Date>): Expectation<Date> {
-    return Expectation.thatActualShould<Date, Date>('have value that is before', expected)
-        .soThat((actualValue, expectedValue) => actualValue.getTime() < expectedValue.getTime());
-}
+/**
+ * Creates an {@apilink Expectation|expectation} that is met when the actual value of type `Date`
+ * is before the expected `Date`.
+ *
+ * ## Ensuring that a given date is after the expected date
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, isBefore } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that(new Date('1995-01-01'), isBefore(new Date('2022-01-01'))),
+ * )
+ * ```
+ *
+ * ## Ensuring that a given date is within the expected date range
+ *
+ * ```ts
+ * import { actorCalled, Expectation, d } from '@serenity-js/core'
+ * import { Ensure, and, isAfter, isBefore } from '@serenity-js/assertions'
+ *
+ * const isWithinDateRange = (lowerBound: Answerable<Date>, upperBound: Answerable<Date>) =>
+ *   Expectation.to(d`have value that is between ${ lowerBound } and ${ upperBound }`)
+ *     .soThatActual(
+ *       and(isAfter(lowerBound), isBefore(upperBound))
+ *     ),
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that(
+ *     new Date('2022-01-01'),
+ *     isWithinDateRange(new Date('1995-01-01'), new Date('2025-01-01'))
+ *   ),
+ * )
+ * ```
+ *
+ * @param expected
+ *
+ * @group Expectations
+ */
+export const isBefore = Expectation.define(
+    'isBefore', 'have value that is before',
+    (actual: Date, expected: Date) =>
+        actual.getTime() < expected.getTime()
+);

package/src/expectations/isCloseTo.ts

@@ -0,0 +1,40 @@
+import { d, Expectation } from '@serenity-js/core';
+
+/**
+ * Produces an {@apilink Expectation|expectation} that is met when the actual value
+ * is within a given ± `absoluteTolerance` range of the `expected` value.
+ *
+ * ## Ensuring that a given floating point number is close to the expected number
+ *
+ * ```ts
+ *  import { actorCalled } from '@serenity-js/core'
+ *  import { Ensure, isCloseTo } from '@serenity-js/assertions'
+ *
+ *  await actorCalled('Iris').attemptsTo(
+ *      Ensure.that(10.123, isCloseTo(10, 0.2))
+ *  )
+ * ```
+ *
+ * @param expected
+ * @param [absoluteTolerance=1e-9]
+ *  Absolute ± tolerance range, defaults to `1e-9`
+ *
+ * @group Expectations
+ */
+export const isCloseTo = Expectation.define(
+    'isCloseTo', (expected, absoluteTolerance = 1e-9) => d`have value close to ${ expected } ±${ absoluteTolerance }`,
+    (actual: number, expected: number, absoluteTolerance = 1e-9) => {
+        // short-circuit exact equality
+        if (actual === expected) {
+            return true;
+        }
+
+        if (! (Number.isFinite(actual) && Number.isFinite(expected))) {
+            return false;
+        }
+
+        const difference = Math.abs(actual - expected)
+
+        return difference <= absoluteTolerance;
+    }
+)

package/src/expectations/isFalse.ts

@@ -2,6 +2,24 @@ import { Expectation } from '@serenity-js/core';
 
 import { equals } from './equals';
 
+/**
+ * Creates an {@apilink Expectation|expectation} that is met when the actual `boolean` value
+ * is `false`.
+ *
+ * ## Ensuring that a given value is false
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, isFalse } from '@serenity-js/assertions'
+ * import { Cookie } from '@serenity-js/web'
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that(Cookie.called('example-regular-cookie').isSecure(), isFalse()),
+ * )
+ * ```
+ *
+ * @group Expectations
+ */
 export function isFalse(): Expectation<boolean> {
-    return Expectation.to<never, boolean>(`equal false`).soThatActual(equals(false));
+    return Expectation.to<boolean>(`equal false`).soThatActual(equals(false));
 }

package/src/expectations/isGreaterThan.ts

@@ -1,6 +1,49 @@
-import { Answerable, Expectation } from '@serenity-js/core';
+import { Expectation } from '@serenity-js/core';
 
-export function isGreaterThan(expected: Answerable<number>): Expectation<number> {
-    return Expectation.thatActualShould<number, number>('have value greater than', expected)
-        .soThat((actualValue, expectedValue) => actualValue > expectedValue);
-}
+/**
+ * Creates an {@apilink Expectation|expectation} that is met when the actual value of type `number`
+ * is greater than the expected `number`.
+ *
+ * ## Ensuring that a given number is greater than the expected number
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, isGreaterThan } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that(10, isGreaterThan(5)),
+ * )
+ * ```
+ *
+ * ## Ensuring that a given number is within the expected range
+ *
+ * ```ts
+ * import { actorCalled, Expectation, d } from '@serenity-js/core'
+ * import { Ensure, and, equals, isGreaterThan, isLessThan, or } from '@serenity-js/assertions'
+ *
+ * const isWithinRange = (lowerBound: Answerable<number>, upperBound: Answerable<number>) =>
+ *   Expectation.to(d`have value that is between ${ lowerBound } and ${ upperBound }`)
+ *     .soThatActual(
+ *       and(
+ *         or(equals(lowerBound), isGreaterThan(lowerBound)),
+ *         or(equals(upperBound), isLessThan(upperBound)),
+ *       )
+ *     ),
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that(
+ *     7,
+ *     isWithinRange(5, 10)
+ *   ),
+ * )
+ * ```
+ *
+ * @param expected
+ *
+ * @group Expectations
+ */
+export const isGreaterThan = Expectation.define(
+    'isGreaterThan', 'have value greater than',
+    (actual: number, expected: number) =>
+        actual > expected,
+)

package/src/expectations/isLessThan.ts

@@ -1,6 +1,49 @@
-import { Answerable, Expectation } from '@serenity-js/core';
+import { Expectation } from '@serenity-js/core';
 
-export function isLessThan(expected: Answerable<number>): Expectation<number> {
-    return Expectation.thatActualShould<number, number>(`have value that's less than`, expected)
-        .soThat((actualValue, expectedValue) => actualValue < expectedValue);
-}
+/**
+ * Creates an {@apilink Expectation|expectation} that is met when the actual value of type `number`
+ * is less than the expected `number`.
+ *
+ * ## Ensuring that a given number is less than the expected number
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, isLessThan } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that(5, isLessThan(10)),
+ * )
+ * ```
+ *
+ * ## Ensuring that a given number is within the expected range
+ *
+ * ```ts
+ * import { actorCalled, Expectation, d } from '@serenity-js/core'
+ * import { Ensure, and, equals, isGreaterThan, isLessThan, or } from '@serenity-js/assertions'
+ *
+ * const isWithinRange = (lowerBound: Answerable<number>, upperBound: Answerable<number>) =>
+ *   Expectation.to(d`have value that is between ${ lowerBound } and ${ upperBound }`)
+ *     .soThatActual(
+ *       and(
+ *         or(equals(lowerBound), isGreaterThan(lowerBound)),
+ *         or(equals(upperBound), isLessThan(upperBound)),
+ *       )
+ *     ),
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that(
+ *     7,
+ *     isWithinRange(5, 10)
+ *   ),
+ * )
+ * ```
+ *
+ * @param expected
+ *
+ * @group Expectations
+ */
+export const isLessThan = Expectation.define(
+    'isLessThan', `have value that's less than`,
+    (actual: number, expected: number) =>
+        actual < expected,
+);

package/src/expectations/isPresent.ts

@@ -1,16 +1,65 @@
-import { Answerable, AnswersQuestions, Expectation, ExpectationMet, ExpectationNotMet, Optional } from '@serenity-js/core';
+import { Answerable, AnswersQuestions, Expectation, ExpectationDetails, ExpectationMet, ExpectationNotMet, Optional } from '@serenity-js/core';
 
 /**
- * @desc
- *  Expectation that the `actual` is not undefined or null.
- *  Also, for `actual` implementing {@link @serenity-js/core/lib/screenplay~Optional}, that `Optional.isPresent()` returns an {@link @serenity-js/core/lib/screenplay~Answerable}
- *  that resolves to `true`
+ * Creates an {@apilink Expectation|expectation} that is met when the `actual` value is not undefined or null.
  *
- * @returns {@serenity-js/core/lib/screenplay/questions~Expectation<Answerable<boolean>, Optional>}
+ * Also, when the `actual` implements {@apilink Optional}, the expectation is met when calling {@apilink Optional.isPresent()}
+ * returns an {@apilink Answerable} that resolves to `true`
  *
- * @see {@link @serenity-js/assertions~Ensure}
- * @see {@link @serenity-js/core/lib/screenplay/questions~Check}
- * @see {@link Wait}
+ * ## Ensuring that a value is defined
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { CallAnApi, Send, GetRequest, LastResponse } from '@serenity-js/rest'
+ * import { Ensure, isPresent } from '@serenity-js/assertions'
+ *
+ * interface Product {
+ *     name: string;
+ * }
+ *
+ * interface ProductsResponse {
+ *     products: Product[];
+ * }
+ *
+ * await actorCalled('Apisitt')
+ *   .whoCan(CallAnApi.at('https://api.example.org'))
+ *   .attemptsTo(
+ *     Send.a(GetRequest.to('/products')),
+ *     Ensure.that(LastResponse.body<ProductsResponse>().products[0], isPresent()),
+ *   )
+ * ```
+ *
+ * ## Checking if a PageElement is present
+ *
+ * ```ts
+ * import { actorCalled, Check } from '@serenity-js/core';
+ * import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright';
+ * import { By, Click, Navigate, PageElement } from '@serenity-js/web';
+ * import { Browser, chromium } from 'playwright';
+ *
+ * class NewsletterSubscription {
+ *   static modal = () =>
+ *     PageElement.located(By.id('newsletter-subscription'))
+ *       .describedAs('newsletter subscription modal')
+ *
+ *   static closeButton = () =>
+ *     PageElement.located(By.class('.close'))
+ *       .of(NewsletterSubscription.modal())
+ *       .describedAs('close button')
+ * }
+ *
+ * const browser = await chromium.launch({ headless: true });
+ *
+ * await actorCalled('Isabela')
+ *   .whoCan(BrowseTheWebWithPlaywright.using(browser))
+ *   .attemptsTo(
+ *     Navigate.to(`https://example.org`),
+ *     Check.whether(NewsletterSubscription.modal(), isPresent())
+ *       .andIfSo(Click.on(NewsletterSubscription.closeButton())),
+ *   )
+ * ```
+ *
+ * @group Expectations
  */
 export function isPresent<Actual>(): Expectation<Actual> {
     return new IsPresent<Actual>();
@@ -42,16 +91,16 @@ class IsPresent<Actual> extends Expectation<Actual> {
 
     constructor() {
         super(
+            'isPresent',
             'become present',
             async (actor: AnswersQuestions, actual: Answerable<Actual>) => {
 
-                const value = await IsPresent.valueToCheck(actual, actor);
-
+                const value  = await IsPresent.valueToCheck(actual, actor);
                 const result = await IsPresent.isPresent(value, actor);
 
                 return result
-                    ? new ExpectationMet('become present', undefined, undefined)
-                    : new ExpectationNotMet('become present', undefined, undefined);
+                    ? new ExpectationMet('become present', ExpectationDetails.of('isPresent'), true, actual)
+                    : new ExpectationNotMet('become present', ExpectationDetails.of('isPresent'), true, actual);
             }
         );
     }

package/src/expectations/isTrue.ts

@@ -2,6 +2,24 @@ import { Expectation } from '@serenity-js/core';
 
 import { equals } from './equals';
 
+/**
+ * Creates an {@apilink Expectation|expectation} that is met when the actual `boolean` value
+ * is `true`.
+ *
+ * ## Ensuring that a given value is true
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, isTrue } from '@serenity-js/assertions'
+ * import { Cookie } from '@serenity-js/web'
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that(Cookie.called('example-secure-cookie').isSecure(), isTrue()),
+ * )
+ * ```
+ *
+ * @group Expectations
+ */
 export function isTrue(): Expectation<boolean> {
-    return Expectation.to<never, boolean>(`equal true`).soThatActual(equals(true));
+    return Expectation.to<boolean>(`equal true`).soThatActual(equals(true));
 }

package/src/expectations/matches.ts

@@ -1,6 +1,26 @@
-import { Answerable, Expectation } from '@serenity-js/core';
+import { Expectation } from '@serenity-js/core';
 
-export function matches(expected: Answerable<RegExp>): Expectation<string> {
-    return Expectation.thatActualShould<RegExp, string>('match', expected)
-        .soThat((actualValue, expectedValue) => expectedValue.test(actualValue));
-}
+/**
+ * Creates an {@apilink Expectation|expectation} that is met when the actual `string` value
+ * matches the `expected` regular expression.
+ *
+ * ## Ensuring that a given string matches a regular expression
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, includes } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that('Hello World!', matches(/[Ww]orld/)),
+ * )
+ * ```
+ *
+ * @param expected
+ *
+ * @group Expectations
+ */
+export const matches = Expectation.define(
+    'matches', 'match',
+    (actual: string, expected: RegExp) =>
+        expected.test(actual),
+);