@serenity-js/assertions 3.0.0-rc.3 → 3.0.0-rc.30

package/src/expectations/property.ts

@@ -1,33 +1,90 @@
-import { AnswersQuestions, Expectation, ExpectationMet, ExpectationNotMet, ExpectationOutcome } from '@serenity-js/core';
-import { formatted } from '@serenity-js/core/lib/io';
+import { Answerable, AnswersQuestions, Expectation, ExpectationMet, ExpectationNotMet } from '@serenity-js/core';
 
-export function property<Actual, Property extends keyof Actual>(
-    propertyName: Property,
-    expectation: Expectation<any, Actual[Property]>,
-): Expectation<Actual[Property], Actual> {
+/**
+ * Creates an {@apilink Expectation|expectation} that is met when the value of
+ * the `actual[propertyName]` meets the `expectation`.
+ *
+ * ## Ensuring that an array has an item
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, property } from '@serenity-js/assertions'
+ *
+ * const list = [ 'hello', 'world' ]
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that(list, property(0, isPresent())),
+ * )
+ * ```
+ *
+ * ## Ensuring that the property meets an expectation
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, property, equals } from '@serenity-js/assertions'
+ *
+ * const list = [ 'hello', 'world' ]
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that(list, property('length', equals(2))),
+ * )
+ * ```
+ *
+ * ## Asserting on a list of objects
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, property, equals } from '@serenity-js/assertions'
+ *
+ * const developers = [{
+ *     name: 'Jan',
+ *     id: '@jan-molak',
+ * }, {
+ *     name: 'John',
+ *     id: '@wakaleo',
+ * }]
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that(
+ *     developers,
+ *     containItemsWhereEachItem(
+ *       property('id', startsWith('@'))
+ *     ),
+ *   ),
+ * )
+ * ```
+ *
+ * @param propertyName
+ * @param expectation
+ *
+ * @group Expectations
+ */
+export function property<Actual extends object, PropertyName extends keyof Actual>(
+    propertyName: PropertyName,
+    expectation: Expectation<Actual[PropertyName]>
+): Expectation<Actual> {
     return new HasProperty(propertyName, expectation);
 }
 
 /**
  * @package
  */
-class HasProperty<Property extends keyof Actual, Actual> extends Expectation<Actual[Property], Actual> {
+class HasProperty<Actual extends object, PropertyName extends keyof Actual> extends Expectation<Actual> {
     constructor(
-        private readonly propertyName: Property,
-        private readonly expectation: Expectation<any, Actual[Property]>,
+        private readonly propertyName: PropertyName,
+        expectation: Expectation<Actual[PropertyName]>,
     ) {
-        super(formatted `have property ${ propertyName } that does ${ expectation }`);
-    }
-
-    answeredBy(actor: AnswersQuestions): (actual: Actual) => Promise<ExpectationOutcome<Actual[Property], any>> {
-
-        return (actual: Actual) =>
-            this.expectation.answeredBy(actor)(actual[this.propertyName])
-                .then((outcome: ExpectationOutcome<any, Actual[Property]>) => {
+        const subject = `have property ${ String(propertyName) } that does ${ expectation }`;
+        super(
+            subject,
+            async (actor: AnswersQuestions, actual: Answerable<Actual>) => {
+                const actualValue = await actor.answer(actual);
+                const outcome = await actor.answer(expectation.isMetFor(actualValue[propertyName]));
 
-                    return outcome instanceof ExpectationMet
-                        ? new ExpectationMet(this.toString(), outcome.expected, actual[this.propertyName])
-                        : new ExpectationNotMet(this.toString(), outcome.expected, actual[this.propertyName]);
-                });
+                return outcome instanceof ExpectationMet
+                    ? new ExpectationMet<any, Actual>(subject, outcome.expected, actualValue)
+                    : new ExpectationNotMet<any, Actual>(subject, outcome.expected, actualValue);
+            },
+        );
     }
 }

package/src/expectations/startsWith.ts

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

package/src/index.ts

@@ -1,3 +1,2 @@
 export * from './Ensure';
 export * from './expectations';
-export { Check, Expectation } from '@serenity-js/core'; // re-exported to avoid breaking backwards compatibility with tests using 2.24.1

package/tsconfig.build.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.build.json",
+  "compilerOptions": {
+    "outDir": "lib",
+    "rootDir": "src"
+  },
+  "include": [
+    "src/**/*.ts"
+  ]
+}

package/tsconfig.eslint.json

@@ -1,10 +0,0 @@
-{
-  "extends": "./tsconfig",
-  "include": [
-    "src/**/*.ts",
-    "spec/**/*.ts"
-  ],
-  "exclude": [
-    "node_modules"
-  ]
-}