From 977c8cfccd7e5fa9b0a6d3c59111aeb06219cca9 Mon Sep 17 00:00:00 2001 From: Timo Tijhof Date: Sun, 6 Feb 2022 02:48:51 +0000 Subject: [PATCH] Docs: Write `assert.propContain()` and `notPropContains()` pages Also cross-link with propEqual pages, and improve those as well, in particular to clarify that these too are recursive in regards to nested objects being comparable using plain objects. Ref https://github.com/qunitjs/qunit/pull/1668. --- docs/assert/notPropContains.md | 79 ++++++++++++++++++++++++++++++++++ docs/assert/notPropEqual.md | 13 +++--- docs/assert/propContain.md | 78 +++++++++++++++++++++++++++++++++ docs/assert/propEqual.md | 19 +++++--- 4 files changed, 176 insertions(+), 13 deletions(-) create mode 100644 docs/assert/notPropContains.md create mode 100644 docs/assert/propContain.md diff --git a/docs/assert/notPropContains.md b/docs/assert/notPropContains.md new file mode 100644 index 000000000..5fa364e24 --- /dev/null +++ b/docs/assert/notPropContains.md @@ -0,0 +1,79 @@ +--- +layout: page-api +title: assert.notPropContains() +excerpt: Check that an object does not contain certain properties. +groups: + - assert +version_added: "unreleased" +--- + +`notPropContains( actual, expected, message = "" )` + +Check that an object does not contain certain properties. + +| name | description | +|------|-------------| +| `actual` | Expression being tested | +| `expected` | Known comparison value | +| `message` (string) | Short description of the actual value | + + +The `notPropContains` assertion compares the subset of properties in the expected object, and tests that these keys are either absent or hold a value that is different according to a strict equality comparison. + +This method is recursive and allows partial comparison of nested objects as well. + +## See also + +* Use [`assert.propContain()`](./propContain.md) to test for the presence and equality of properties instead. + +## Examples + +```js +QUnit.test( "example", assert => { + + const result = { + foo: 0, + vehicle: { + timeCircuits: "on", + fluxCapacitor: "fluxing", + engine: "running" + }, + quux: 1 + }; + + // succeeds, property "timeCircuits" is actually "on" + assert.notPropContains( result, { + vehicle: { + timeCircuits: "off" + } + } ); + + // succeeds, property "wings" is not in the object + assert.notPropContains( result, { + vehicle: { + wings: "flapping" + } + } ); + + function Point( x, y ) { + this.x = x; + this.y = y; + } + + assert.notPropContains( + new Point( 10, 20 ), + { z: 30 } + ); + + const nested = { + north: [ /* ... */ ], + east: new Point( 10, 20 ), + south: [ /* ... */ ], + west: [ /* ... */ ] + }; + + assert.notPropContains( nested, { east: new Point( 88, 42 ) } ); + assert.notPropContains( nested, { east: { x: 88 } } ); + +} ); +``` diff --git a/docs/assert/notPropEqual.md b/docs/assert/notPropEqual.md index 1381f8134..1d7c4f315 100644 --- a/docs/assert/notPropEqual.md +++ b/docs/assert/notPropEqual.md @@ -1,7 +1,7 @@ --- layout: page-api title: assert.notPropEqual() -excerpt: A strict comparison of an object's own properties, checking for inequality. +excerpt: Compare an object's own properties for inequality. groups: - assert redirect_from: @@ -11,7 +11,7 @@ version_added: "1.11.0" `notPropEqual( actual, expected, message = "" )` -A strict comparison of an object's own properties, checking for inequality. +Compare an object's own properties using a strict inequality comparison. | name | description | |------|-------------| @@ -19,13 +19,14 @@ A strict comparison of an object's own properties, checking for inequality. | `expected` | Known comparison value | | `message` (string) | A short description of the assertion | -The `notPropEqual` assertion uses the strict inverted comparison operator (`!==`) to compare the actual and expected arguments as Objects regarding only their properties but not their constructors. +The `notPropEqual` assertion compares only an object's own properties, using the strict inquality operator (`!==`). -When they aren't equal, the assertion passes; otherwise, it fails. When it fails, both actual and expected values are displayed in the test result, in addition to a given message. +The test passes if there are properties with different values, or extra properties, or missing properties. -[`assert.equal()`](./equal.md) can be used to test equality. +## See also -[`assert.propEqual()`](./propEqual.md) can be used to test strict equality of an Object properties. +* Use [`assert.notPropContain()`](./notPropContain.md) to only check for the absence or inequality of some properties. +* Use [`assert.propEqual()`](./propEqual.md) to test for equality of properties instead. ## Examples diff --git a/docs/assert/propContain.md b/docs/assert/propContain.md new file mode 100644 index 000000000..3d3781611 --- /dev/null +++ b/docs/assert/propContain.md @@ -0,0 +1,78 @@ +--- +layout: page-api +title: assert.propContain() +excerpt: Check that an object contains certain properties. +groups: + - assert +version_added: "unreleased" +--- + +`propContain( actual, expected, message = "" )` + +Check that an object contains certain properties. + +| name | description | +|------|-------------| +| `actual` | Expression being tested | +| `expected` | Known comparison value | +| `message` (string) | Short description of the actual value | + + +The `propContain` assertion compares only the **subset** of properties in the expected object, +and tests that these keys exist as own properties with strictly equal values. + +This method is recursive and allows partial comparison of nested objects as well. + +## See also + +* Use [`assert.propEqual()`](./propEqual.md) to compare all properties, considering extra properties as unexpected. +* Use [`assert.notPropContain()`](./notPropContain.md) to test for the absence or inequality of certain properties. + +## Examples + +```js +QUnit.test( "example", assert => { + + const result = { + foo: 0, + vehicle: { + timeCircuits: "on", + fluxCapacitor: "fluxing", + engine: "running" + }, + quux: 1 + }; + + assert.propContains( result, { + foo: 0, + vehicle: { fluxCapacitor: "fluxing" } + } ); + + function Point( x, y ) { + this.x = x; + this.y = y; + } + + assert.propContains( + new Point( 10, 20 ), + { y: 20 } + ); + + assert.propContains( + [ "a", "b" ], + { 1: "b" } + ); + + const nested = { + north: [ /* ... */ ], + east: new Point( 10, 20 ), + south: [ /* ... */ ], + west: [ /* ... */ ] + }; + + assert.propContains( nested, { east: new Point( 10, 20 ) } ); + assert.propContains( nested, { east: { x: 10, y: 20 } } ); + assert.propContains( nested, { east: { x: 10 } } ); + +} ); +``` diff --git a/docs/assert/propEqual.md b/docs/assert/propEqual.md index 674257b0f..c21203a31 100644 --- a/docs/assert/propEqual.md +++ b/docs/assert/propEqual.md @@ -1,7 +1,7 @@ --- layout: page-api title: assert.propEqual() -excerpt: A strict type and value comparison of an object's own properties. +excerpt: Compare an object's own properties. groups: - assert redirect_from: @@ -11,7 +11,7 @@ version_added: "1.11.0" `propEqual( actual, expected, message = "" )` -A strict type and value comparison of an object's own properties. +Compare an object's own properties using a strict comparison. | name | description | |------|-------------| @@ -19,15 +19,20 @@ A strict type and value comparison of an object's own properties. | `expected` | Known comparison value | | `message` (string) | A short description of the assertion | -The `propEqual` assertion provides strictly (`===`) comparison of Object properties. Unlike [`assert.deepEqual()`](./deepEqual.md), this assertion can be used to compare two objects made with different constructors or prototypes. +The `propEqual` assertion compares only an object's own properties. This means the expected value does not need to be an instance of the same class or otherwise inherit the same prototype, unlike with [`assert.deepEqual()`](./deepEqual.md). -[`assert.strictEqual()`](./strictEqual.md) can be used to test strict equality. +The assertion fails if values differ, if there are additional properties, or if some properties are missing. -[`assert.notPropEqual()`](./notPropEqual.md) can be used to explicitly test strict inequality of Object properties. +This method is recursive and can compare any nested or complex object via a plain object. + +## See also + +* Use [`assert.propContain()`](./propContain.md) to only check a subset of properties. +* Use [`assert.notPropEqual()`](./notPropEqual.md) to test for the inequality of object properties instead. ## Examples -Compare the properties values of two objects. +Compare the property values of two objects. ```js QUnit.test( "example", assert => { @@ -43,7 +48,7 @@ QUnit.test( "example", assert => { const foo = new Foo(); // succeeds, own properties are strictly equal, - // and inherited properties (such as which object constructor) are ignored. + // and inherited properties (such as which constructor) are ignored. assert.propEqual( foo, { x: 1, y: 2