Skip to content

Commit

Permalink
Make assertions return Booleans
Browse files Browse the repository at this point in the history 
This makes most of the built-in assertion functions return Boolean
values, `true` when the assertion succeeds and `false` when the
assertion fails.

This is intended to allow a user to emulate the assertion function
throwing an exception by allowing control flow to only proceed if the
assertion passes, something like:

```
if (t.is(foo, 42)) {
  // Do some other things that only make sense when `foo` is `42`.
}
```

The various "throws" functions are left alone since they already return
exception values. `snapshot` is left alone since it doesn't seem to make
much sense to make it return a Boolean in this way.

`pass` and `fail` are somewhat special since they act more as "flags"
that tell the test runner to pass or fail the test and don't actually do
any asserting. In their cases, their returned flag values are chosen for
use as analogues of `if (true) { ... }` and `if (false) { ... }`.

Fixes issue avajs#2455.
  • Loading branch information
@jasontbradshaw
jasontbradshaw committed Oct 13, 2020
1 parent b71f396 commit ca0c975
Show file tree
Hide file tree
Showing 3 changed files with 593 additions and 448 deletions.
162 changes: 119 additions & 43 deletions index.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,40 +39,68 @@ export type SnapshotOptions = {
};

export interface Assertions {
/** Assert that `actual` is [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy). Comes with power-assert. */
/**
* Assert that `actual` is
* [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy),
* returning Boolean indicating whether the assertion passes. Comes with
* power-assert.
*/
assert: AssertAssertion;

/** Assert that `actual` is [deeply equal](https://github.com/concordancejs/concordance#comparison-details) to `expected`. */
/**
* Assert that `actual` is [deeply
* equal](https://github.com/concordancejs/concordance#comparison-details) to
* `expected`, returning Boolean indicating whether the assertion passes.
*/
deepEqual: DeepEqualAssertion;

/** Assert that `actual` is like `expected`. */
/**
* Assert that `value` is like `selector`, returning Boolean indicating
* whether the assertion passes.
*/
like: LikeAssertion;

/** Fail the test. */
/** Fail the test, always returning `false`. */
fail: FailAssertion;

/** Assert that `actual` is strictly false. */
/**
* Assert that `actual` is strictly false, returning Boolean indicating
* whether the assertion passes.
*/
false: FalseAssertion;

/** Assert that `actual` is [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy). */
/**
* Assert that `actual` is
* [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy), returning
* Boolean whether the assertion passes.
*/
falsy: FalsyAssertion;

/**
* Assert that `actual` is [the same
* value](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) as `expected`.
* value](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is)
* as `expected`, returning Boolean indicating whether the assertion passes.
*/
is: IsAssertion;

/**
* Assert that `actual` is not [the same
* value](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) as `expected`.
* value](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is)
* as `expected`, returning Boolean indicating whether the assertion passes.
*/
not: NotAssertion;

/** Assert that `actual` is not [deeply equal](https://github.com/concordancejs/concordance#comparison-details) to `expected`. */
/**
* Assert that `actual` is not [deeply
* equal](https://github.com/concordancejs/concordance#comparison-details) to
* `expected`, returning Boolean indicating whether the assertion passes.
*/
notDeepEqual: NotDeepEqualAssertion;

/** Assert that `string` does not match the regular expression. */
/**
* Assert that `string` does not match the regular expression, returning
* Boolean indicating whether the assertion passes.
*/
notRegex: NotRegexAssertion;

/** Assert that the function does not throw. */
Expand All @@ -81,10 +109,13 @@ export interface Assertions {
/** Assert that the async function does not throw, or that the promise does not reject. Must be awaited. */
notThrowsAsync: NotThrowsAsyncAssertion;

/** Count a passing assertion. */
/** Count a passing assertion, always returning `true`. */
pass: PassAssertion;

/** Assert that `string` matches the regular expression. */
/**
* Assert that `string` matches the regular expression, returning Boolean
* indicating whether the assertion passes.
*/
regex: RegexAssertion;

/**
Expand All @@ -105,56 +136,82 @@ export interface Assertions {
*/
throwsAsync: ThrowsAsyncAssertion;

/** Assert that `actual` is strictly true. */
/**
* Assert that `actual` is strictly true, returning Boolean indicating
* whether the assertion passes.
*/
true: TrueAssertion;

/** Assert that `actual` is [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy). */
/**
* Assert that `actual` is
* [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy),
* returning Boolean indicating whether the assertion passes.
*/
truthy: TruthyAssertion;
}

export interface AssertAssertion {
/** Assert that `actual` is [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy). Comes with power-assert. */
(actual: any, message?: string): void;
/**
* Assert that `actual` is
* [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy),
* returning Boolean indicating whether the assertion passes. Comes with
* power-assert.
*/
(actual: any, message?: string): boolean;

/** Skip this assertion. */
skip(actual: any, message?: string): void;
}

export interface DeepEqualAssertion {
/** Assert that `actual` is [deeply equal](https://github.com/concordancejs/concordance#comparison-details) to `expected`. */
<ValueType = any>(actual: ValueType, expected: ValueType, message?: string): void;
/**
* Assert that `actual` is [deeply
* equal](https://github.com/concordancejs/concordance#comparison-details) to
* `expected`, returning Boolean indicating whether the assertion passes.
*/
<ValueType = any>(actual: ValueType, expected: ValueType, message?: string): boolean;

/** Skip this assertion. */
skip(actual: any, expected: any, message?: string): void;
}

export interface LikeAssertion {
/** Assert that `value` is like `selector`. */
(value: any, selector: Record<string, any>, message?: string): void;
/**
* Assert that `value` is like `selector`, returning Boolean indicating
* whether the assertion passes.
*/
(value: any, selector: Record<string, any>, message?: string): boolean;

/** Skip this assertion. */
skip(value: any, selector: any, message?: string): void;
}

export interface FailAssertion {
/** Fail the test. */
(message?: string): void;
/** Fail the test, always returning `false`. */
(message?: string): false;

/** Skip this assertion. */
skip(message?: string): void;
}

export interface FalseAssertion {
/** Assert that `actual` is strictly false. */
(actual: any, message?: string): void;
/**
* Assert that `actual` is strictly false, returning Boolean indicating
* whether the assertion passes.
*/
(actual: any, message?: string): boolean;

/** Skip this assertion. */
skip(actual: any, message?: string): void;
}

export interface FalsyAssertion {
/** Assert that `actual` is [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy). */
(actual: any, message?: string): void;
/**
* Assert that `actual` is
* [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy), returning
* Boolean whether the assertion passes.
*/
(actual: any, message?: string): boolean;

/** Skip this assertion. */
skip(actual: any, message?: string): void;
Expand All @@ -163,9 +220,10 @@ export interface FalsyAssertion {
export interface IsAssertion {
/**
* Assert that `actual` is [the same
* value](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) as `expected`.
* value](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is)
* as `expected`, returning Boolean indicating whether the assertion passes.
*/
<ValueType = any>(actual: ValueType, expected: ValueType, message?: string): void;
<ValueType = any>(actual: ValueType, expected: ValueType, message?: string): boolean;

/** Skip this assertion. */
skip(actual: any, expected: any, message?: string): void;
Expand All @@ -174,25 +232,33 @@ export interface IsAssertion {
export interface NotAssertion {
/**
* Assert that `actual` is not [the same
* value](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) as `expected`.
* value](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is)
* as `expected`, returning Boolean indicating whether the assertion passes.
*/
<ValueType = any>(actual: ValueType, expected: ValueType, message?: string): void;
<ValueType = any>(actual: ValueType, expected: ValueType, message?: string): boolean;

/** Skip this assertion. */
skip(actual: any, expected: any, message?: string): void;
}

export interface NotDeepEqualAssertion {
/** Assert that `actual` is not [deeply equal](https://github.com/concordancejs/concordance#comparison-details) to `expected`. */
<ValueType = any>(actual: ValueType, expected: ValueType, message?: string): void;
/**
* Assert that `actual` is not [deeply
* equal](https://github.com/concordancejs/concordance#comparison-details) to
* `expected`, returning Boolean indicating whether the assertion passes.
*/
<ValueType = any>(actual: ValueType, expected: ValueType, message?: string): boolean;

/** Skip this assertion. */
skip(actual: any, expected: any, message?: string): void;
}

export interface NotRegexAssertion {
/** Assert that `string` does not match the regular expression. */
(string: string, regex: RegExp, message?: string): void;
/**
* Assert that `string` does not match the regular expression, returning
* Boolean indicating whether the assertion passes.
*/
(string: string, regex: RegExp, message?: string): boolean;

/** Skip this assertion. */
skip(string: string, regex: RegExp, message?: string): void;
Expand All @@ -218,16 +284,19 @@ export interface NotThrowsAsyncAssertion {
}

export interface PassAssertion {
/** Count a passing assertion. */
(message?: string): void;
/** Count a passing assertion, always returning `true`. */
(message?: string): true;

/** Skip this assertion. */
skip(message?: string): void;
}

export interface RegexAssertion {
/** Assert that `string` matches the regular expression. */
(string: string, regex: RegExp, message?: string): void;
/**
* Assert that `string` matches the regular expression, returning Boolean
* indicating whether the assertion passes.
*/
(string: string, regex: RegExp, message?: string): boolean;

/** Skip this assertion. */
skip(string: string, regex: RegExp, message?: string): void;
Expand Down Expand Up @@ -296,16 +365,23 @@ export interface ThrowsAsyncAssertion {
}

export interface TrueAssertion {
/** Assert that `actual` is strictly true. */
(actual: any, message?: string): void;
/**
* Assert that `actual` is strictly true, returning Boolean indicating
* whether the assertion passes.
*/
(actual: any, message?: string): boolean;

/** Skip this assertion. */
skip(actual: any, message?: string): void;
}

export interface TruthyAssertion {
/** Assert that `actual` is [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy). */
(actual: any, message?: string): void;
/**
* Assert that `actual` is
* [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy),
* returning Boolean indicating whether the assertion passes.
*/
(actual: any, message?: string): boolean;

/** Skip this assertion. */
skip(actual: any, message?: string): void;
Expand Down Expand Up @@ -433,7 +509,7 @@ export interface CbExecutionContext<Context = unknown> extends ExecutionContext<
end(error?: any): void;
}

export type ImplementationResult = PromiseLike<void> | Subscribable | void;
export type ImplementationResult = PromiseLike<void> | Subscribable | boolean | void;
export type Implementation<Context = unknown> = (t: ExecutionContext<Context>) => ImplementationResult;
export type CbImplementation<Context = unknown> = (t: CbExecutionContext<Context>) => ImplementationResult;

Expand Down
Loading

0 comments on commit ca0c975

Please sign in to comment.