@serenity-js/assertions
Version:
Serenity/JS universal assertion library supporting all types of functional tests, including both web and REST API scenarios
149 lines • 6.54 kB
JavaScript
;
Object.defineProperty(exports, "__esModule", { value: true });
exports.Ensure = void 0;
const core_1 = require("@serenity-js/core");
const EnsureEventually_1 = require("./EnsureEventually");
/**
* The [interaction](https://serenity-js.org/api/core/class/Interaction/) to `Ensure`
* verifies if the resolved value of the provided [`Answerable`](https://serenity-js.org/api/core/#Answerable)
* meets the specified [`Expectation`](https://serenity-js.org/api/core/class/Expectation/).
* If not, it throws an [`AssertionError`](https://serenity-js.org/api/core/class/AssertionError/).
*
* Use `Ensure` to verify the state of the system under test.
*
* ## Basic usage with static values
* ```ts
* import { actorCalled } from '@serenity-js/core'
* import { Ensure, equals } from '@serenity-js/assertions'
*
* await actorCalled('Erica').attemptsTo(
* Ensure.that('Hello world!', equals('Hello world!'))
* )
* ```
*
* ## Composing expectations with `and`
*
* ```ts
* import { actorCalled } from '@serenity-js/core'
* import { and, Ensure, startsWith, endsWith } from '@serenity-js/assertions'
*
* await actorCalled('Erica').attemptsTo(
* Ensure.that('Hello world!', and(startsWith('Hello'), endsWith('!'))
* )
* ```
*
* ## Overriding the type of Error thrown upon assertion failure
*
* ```ts
* import { actorCalled, TestCompromisedError } from '@serenity-js/core'
* import { and, Ensure, startsWith, endsWith } from '@serenity-js/assertions'
* import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
*
* await actorCalled('Erica')
* .whoCan(CallAnApi.at('https://example.com'))
* .attemptsTo(
* Send.a(GetRequest.to('/api/health')),
* Ensure.that(LastResponse.status(), equals(200))
* .otherwiseFailWith(TestCompromisedError, 'The server is down, please cheer it up!')
* )
* ```
*
* @group Activities
*/
class Ensure extends core_1.Interaction {
actual;
expectation;
/**
* Creates an [interaction](https://serenity-js.org/api/core/class/Interaction/) to `Ensure`, which
* verifies if the resolved value of the provided [`Answerable`](https://serenity-js.org/api/core/#Answerable)
* meets the specified [`Expectation`](https://serenity-js.org/api/core/class/Expectation/).
* If not, it immediately throws an [`AssertionError`](https://serenity-js.org/api/core/class/AssertionError/).
*
* @param {Answerable<Actual_Type>} actual
* An [`Answerable`](https://serenity-js.org/api/core/#Answerable) describing the actual state of the system.
*
* @param {Expectation<Actual_Type>} expectation
* An [`Expectation`](https://serenity-js.org/api/core/class/Expectation/) you expect the `actual` value to meet
*
* @returns {Ensure<Actual_Type>}
*/
static that(actual, expectation) {
return new Ensure(actual, expectation, core_1.Activity.callerLocation(5));
}
/**
* Creates an [interaction](https://serenity-js.org/api/core/class/Interaction/) to [`EnsureEventually`](https://serenity-js.org/api/assertions/class/EnsureEventually/),
* which verifies if the resolved value of the provided [`Answerable`](https://serenity-js.org/api/core/#Answerable)
* meets the specified [`Expectation`](https://serenity-js.org/api/core/class/Expectation/) within the expected timeframe.
*
* If the expectation is not met by the time the timeout expires, the interaction throws an [`AssertionError`](https://serenity-js.org/api/core/class/AssertionError/).
*
* @param {Answerable<Actual_Type>} actual
* An [`Answerable`](https://serenity-js.org/api/core/#Answerable) describing the actual state of the system.
*
* @param {Expectation<Actual_Type>} expectation
* An [`Expectation`](https://serenity-js.org/api/core/class/Expectation/) you expect the `actual` value to meet
*
* @returns {Ensure<Actual_Type>}
*/
static eventually(actual, expectation) {
return new EnsureEventually_1.EnsureEventually(actual, expectation, core_1.Activity.callerLocation(5));
}
/**
* @param actual
* @param expectation
* @param location
*/
constructor(actual, expectation, location) {
super((0, core_1.the) `#actor ensures that ${actual} does ${expectation}`, location);
this.actual = actual;
this.expectation = expectation;
}
/**
* @inheritDoc
*/
async performAs(actor) {
const outcome = await actor.answer(this.expectation.isMetFor(this.actual));
if (outcome instanceof core_1.ExpectationNotMet) {
const actualDescription = this.actual === undefined
? 'undefined'
: core_1.Question.formattedValue().of(this.actual);
const message = `Expected ${actualDescription} to ${outcome.message}`;
throw core_1.RaiseErrors.as(actor).create(core_1.AssertionError, {
message,
expectation: outcome.expectation,
diff: { expected: outcome.expected, actual: outcome.actual },
location: this.instantiationLocation(),
});
}
if (!(outcome instanceof core_1.ExpectationMet)) {
throw new core_1.LogicError((0, core_1.f) `Expectation#isMetFor(actual) should return an instance of an ExpectationOutcome, not ${outcome}`);
}
}
/**
* Overrides the default [`AssertionError`](https://serenity-js.org/api/core/class/AssertionError/) thrown when
* the actual value does not meet the expectation.
*
* @param typeOfRuntimeError
* A constructor function producing a subtype of [`RuntimeError`](https://serenity-js.org/api/core/class/RuntimeError/) to throw, e.g. [`TestCompromisedError`](https://serenity-js.org/api/core/class/TestCompromisedError/)
*
* @param message
* The message explaining the failure
*/
otherwiseFailWith(typeOfRuntimeError, message) {
const location = this.instantiationLocation();
return core_1.Interaction.where(this.toString(), async (actor) => {
try {
await this.performAs(actor);
}
catch (error) {
throw core_1.RaiseErrors.as(actor).create(typeOfRuntimeError, {
message: message ?? error.message,
location,
cause: error
});
}
});
}
}
exports.Ensure = Ensure;
//# sourceMappingURL=Ensure.js.map