/cc @nodejs/assert. This doesn't seem like a bad idea to me.

so the difference between this and deepEqual is just that it only checks present properties on the "actual" against the "expected"? could this just be an option to deepEqual?

so the difference between this and deepEqual is just that it only checks present properties on the "actual" against the "expected"?

yes.

could this just be an option to deepEqual?

Well, I guess so, but i'm more convinced that it should be the same as many other testing frameworks as a dedicated method.

To me "assert to match object" is really not something I could understand without reading its docs, so I would prefer if we picked a different name. I think adding allowSuperset option to deepStrictEqual or something like that would make the most sense, and we can always expose an alias later if we feel the need (just my two cents, feel free to disagree). PRs welcome :)

+1 on that. assert.throws already supports something similar

could this just be an option to deepEqual?

imo no. the current signature of deepEqual is assert.deepEqual(actual, expected[, message]), and if we were to maintain backwards compatibility, we would need to add the option after message. but in order for people to use this new option, they would be required to define a message which they may not want to.

A way to make this would would require a soft breaking change with a new signature of:

deepEqual<T>(actual: unknown, expected: T, messageOrOption?: string | {
  message?: string;
  superset?: boolean;
})

@aduh95 I agree matchObject isn't a great name if it were to work with arrays (as does jest toMatchObject), but I also don't like adding an option to deepStrictEqual for the same reason as my previous comment.

How about deepSupersetStrictEqual? We still want the primitives to be compared using ===. Maybe never add legacy deepSupersetEqual to node:assert but only add it to node:assert/strict?

I think it would be fine to make the optional third argument an options object if not a string, as you suggested - and will ensure future compatibility for additional options.

"superset" is a confusing name for this behavior; "allowExtraProperties", maybe?

Just extending the deepStrictEqual into this signature would not result in a breaking change:

function deepStrictEqual<T>(actual: unknown, expected: T, message?: string | Error): asserts actual is T;
function deepStrictEqual<T>(actual: unknown, expected: T, options?: { superset?: boolean }, message?: string | Error): asserts actual is T;

I'm still not sure if an attribute would have a better DX:

// attribute
assert.deepStrictEqual(
  obj,
  {
    a: 1,
    b: 2
  },
  {
    superset: true
  }
);

// custom method
assert.deepSupersetEqual(obj, {
  a: 1,
  b: 2
});

what is the downside of a new method? @aduh95

It's verbose, and another thing to learn, and having two methods that are identical except for one aspect is strange when it could be one method with an option.

It's verbose, and another thing to learn

But wouldn't this behavior align with many other testing frameworks?

Not all of them - iirc, in jasmine you’d use a special matcher wrapper around the object to indicate a partial match

https://jasmine.github.io/api/edge/jasmine.html#.objectContaining

Either way tho, by and large there simply isn't a single cohesive ecosystem consensus around any part of testing. The downside of that is that node runs the risk of conflating patterns and confusing users; the upside is that node is free to make its own decisions.

I agree, either way we should make a decision, right? What options are being considered? Should I make a poll?

I don't want to build by committee. I rather have one person do the leg work and make a recommendation. People are then free to criticize and make another recommendation if they so please.

I'd love to work on this feature, could anyone give me a heads up on where to start? Apparently I should start supporting the keyCheck function used in innerDeepEqual, to just compare properties of val2 in val1 and not in both sides

That sounds right. It's called assertSubset in a few other libraries btw. A wonderful feature if you're ever working with objects with timestamps.

I have a working implementation and I'll open a PR for it soon (I need to finish updating the docs, add more tests and make sure the error message is not weird).

The error message can't display a diff for now as the object tested for might highly deviate and we need a new implementation for the diff.

How to expose it can still be discussed. I think it's easiest and most user friendly to have a separate API next to deepStrictEqual() due to the current APIs arguments, the implementation deviates in multiple spots in a way that documenting that would become difficult and the use cases are just different (full equality vs. partial).
Having e.g., assert.deepStrictEqual(actual, assert.partial(expected)) is also not as readable as assert.contains(actual, expected).

Looking at it without context, assert.contains would probably imply, because it is very similar, that we are looking whether a string is contained within another string. I'd expect assert.contains(a, b) to be the same as assert.ok(a.contains(b)), given a and b are strings.

I still think the name deepSupersetEqual fits better.

Has anyone ever considered a DX like the following?

assert.deepStrictEqual(something, assert.objectContaining(expected))