tungsten 0.6.2 → 0.7.0

package/dist/testing/ensure.js

@@ -0,0 +1,522 @@
+function _defineProperty(e, r, t) { return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, { value: t, enumerable: !0, configurable: !0, writable: !0 }) : e[r] = t, e; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+import { styleText } from 'node:util';
+import deepEqual from 'deep-eql';
+import { ContentNodeElementIsComponent, ContentNodeElementIsHtml, ContentNodeIsArray, ContentNodeIsElement, ContentNodeIsLiteral, IsContentNode } from '../ContentNode.js';
+import { $fragment, $props, $type } from '../contentNodeSymbols.js';
+import { componentTypeIdentityKey } from '../hmr/componentIdentity.js';
+// exported after
+const _ensure = withMembers(ensure, quantifiers(fact => fact));
+export { _ensure as ensure }; // naming
+// read once: an ends object holds no run state, as each run starts its facts afresh
+export const {
+  no,
+  none,
+  one,
+  two,
+  three,
+  a,
+  an,
+  some,
+  all,
+  count
+} = _ensure;
+function quantifiers(finish) {
+  return {
+    get no() {
+      return ends('no', counting(count => count === 0, 0), finish);
+    },
+    get none() {
+      return ends('none', counting(count => count === 0, 0), finish, 'no');
+    },
+    get one() {
+      return ends('one', counting(count => count === 1, 1), finish);
+    },
+    get two() {
+      return ends('two', counting(count => count === 2, 2), finish);
+    },
+    get three() {
+      return ends('three', counting(count => count === 3, 3), finish);
+    },
+    get a() {
+      return ends('a', counting(count => count === 1, 1), finish);
+    },
+    get an() {
+      return ends('an', counting(count => count === 1, 1), finish);
+    },
+    count: num => ends(`count(${num})`, counting(count => count === num, num), finish, String(num)),
+    get some() {
+      return ends('some', () => {
+        let count = 0;
+        return [match => {
+          if (match) ++count;
+          return count > 0;
+        }, () => count > 0 ? undefined : {
+          actual: 0,
+          expected: '1 or more',
+          saw: 'saw 0',
+          showDiff: false
+        }];
+      }, finish);
+    },
+    // every sighting of its kind must match, and there must be one: all of none proves nothing
+    get all() {
+      return ends('all', () => {
+        let count = 0;
+        return [match => {
+          if (match) ++count;
+        }, ofKind => ofKind > 0 && count === ofKind ? undefined : {
+          actual: count,
+          expected: ofKind,
+          saw: `saw ${count} of ${ofKind}`,
+          showDiff: ofKind > 0
+        }];
+      }, finish, 'every');
+    }
+  };
+}
+// the facts of a list as prose, joined: (one <li> and no <b>)
+const spokenList = facts => `(${facts.map(fact => fact[5]).join(' and ')})`;
+// a value as JSX writes it in a prop: title="x", size={3}
+const jsxValue = value => typeof value === 'string' ? `"${value}"` : `{${display(value)}}`;
+// each end says only what a sighting must be, and how it reads in a failure;
+// ensure() starts the requirement
+// spoken: the quantifier as prose, where it differs - none as no, count(3) as 3
+function ends(quantifier, requirement, finish, spoken = quantifier) {
+  const fact = (kind, test, end, prose, explain) => finish([kind, test, requirement, quantifier, end, `${spoken} ${prose}`, explain]);
+  const many = !['one', 'a', 'an', 'every', '1'].includes(spoken);
+  const noun = word => !many ? word : word.endsWith('s') ? `${word}es` : `${word}s`;
+  // a scoped fact is the outer kind, passing where the inner facts pass on the sightings
+  // scopeOf gives for a sighting
+  const scoped = (kind, end, prose, scopeOf) => (inner, to, proseTo) => {
+    const facts = inner.map(each => forKind(each, kind));
+    return fact(kind, scopeTest(scopeOf, facts), `${end}.${to}`, `${prose} ${proseTo}`, scopeExplain(scopeOf, facts));
+  };
+  // alone: present. with: facts on the element itself, its children among them
+  const element = (kind, end, prose, own) => {
+    const within = scoped(kind, end, prose, seen => own(seen));
+    const below = scoped(kind, end, prose, childrenScope);
+    const children = withMembers(facts => below(facts, `with.children(${listed(facts)})`, `with ${spokenList(facts)} in its children`), quantifiers(inner => below([inner], `with.children.${chained(inner)}`, `with ${inner[5]} in its children`)));
+    return Object.assign(fact(kind, () => true, end, prose), {
+      // facts, or a fn given the props for what facts cannot say
+      with: withMembers(withMembers(facts => Array.isArray(facts) ? within(facts, `with(${listed(facts)})`, `with ${spokenList(facts)}`) : fact(kind, seen => facts(seen), `${end}.with(${fnName(facts)})`, `${prose} passing ${fnName(facts)}`), quantifiers(inner => within([inner], `with.${chained(inner)}`, `with ${inner[5]}`))), {
+        children
+      })
+    });
+  };
+  // the text ends differ only in the sighting they read and whether case matters
+  const stringEnd = (kind, name, what, ci = false) => {
+    const norm = text => ci ? lower(text) : text;
+    const read = (seen, met) => typeof seen === 'string' && met(norm(seen));
+    const said = (ci ? 'case-insensitive ' : '') + noun(what);
+    return Object.assign(text => fact(kind, seen => read(seen, found => found === norm(text)), `${name}('${text}')`, (ci ? 'case-insensitive ' : '') + `'${text}' ${noun(what)}`), {
+      contains: substring => fact(kind, seen => read(seen, found => found.includes(norm(substring))), `${name}.contains('${substring}')`, `${said} containing '${substring}'`),
+      matches: regex => fact(kind, matching(regex, ci ? 'i' : ''), `${name}.matches(${String(regex)})`, `${said} matching ${String(regex)}`)
+    });
+  };
+  return {
+    text: stringEnd('text', 'text', 'text node'),
+    textCi: stringEnd('text', 'textCi', 'text node', true),
+    interruptedText: stringEnd('interruptedText', 'interruptedText', 'element text'),
+    html: tag => element(`html:${tag}`, `html('${tag}')`, `<${tag}>`, props => htmlOwnSightings(tag, props)),
+    component: name => element(`component:${name}`, `component('${name}')`, `<${name}>`, props => componentOwnSightings(name, props)),
+    fragment: () => fact('fragment', () => true, 'fragment()', noun('fragment')),
+    className: className => fact('className', seen => className === undefined || seen === className, className === undefined ? 'className()' : `className('${className}')`, className === undefined ? noun('class') : `class="${className}"`),
+    id: id => fact('id', seen => id === undefined || seen === id, id === undefined ? 'id()' : `id('${id}')`, id === undefined ? noun('id') : `id="${id}"`),
+    // prop() alone: passed, whatever the value - undefined included, as the tree has the key.
+    // .is: the value raw, compared by ===, so a handler or ref is matched by reference
+    prop: prop => Object.assign(fact(`prop:${prop}`, () => true, `prop('${prop}')`, `${prop} ${noun('prop')}`), {
+      is: value => fact(`prop:${prop}`, seen => seen === value, `prop('${prop}').is(${display(value)})`, `${prop}=${jsxValue(value)}`),
+      contains: substring => fact(`prop:${prop}`, seen => typeof seen === 'string' && seen.includes(substring), `prop('${prop}').contains('${substring}')`, `${prop} containing '${substring}'`),
+      matches: regex => fact(`prop:${prop}`, matching(regex), `prop('${prop}').matches(${String(regex)})`, `${prop} matching ${String(regex)}`),
+      // chai's deep.equal, which is deep-eql
+      exact: value => fact(`prop:${prop}`, seen => deepEqual(seen, value), `prop('${prop}').exact(${display(value)})`, `${prop} deep-equal to ${display(value)}`),
+      subset: shape => fact(`prop:${prop}`, seen => contains(shape, seen, 'anywhere'), `prop('${prop}').subset(${display(shape)})`, `${prop} with subset ${display(shape)}`),
+      duck: shape => fact(`prop:${prop}`, seen => contains(shape, seen, 'inPlace'), `prop('${prop}').duck(${display(shape)})`, `${prop} shaped like ${display(shape)}`),
+      // opt-in: a content-like prop may not be rendered, so it is walked only on asking.
+      // Alone: the value is content; with: facts on its whole tree, root included
+      content: () => {
+        const end = `prop('${prop}').content()`;
+        const prose = `${prop} holding content`;
+        const within = scoped(`prop:${prop}`, end, prose, seen => IsContentNode(seen) ? contentSightings(seen) : undefined);
+        return Object.assign(fact(`prop:${prop}`, IsContentNode, end, prose), {
+          with: withMembers(facts => within(facts, `with(${listed(facts)})`, `with ${spokenList(facts)}`), quantifiers(inner => within([inner], `with.${chained(inner)}`, `with ${inner[5]}`)))
+        });
+      }
+    })
+  };
+}
+// fields as sxy-assert's, for a runner to read; showDiff where actual and expected are counts
+export class EnsureError extends Error {
+  constructor(message, actual, expected, operator, showDiff) {
+    super(message);
+    _defineProperty(this, "actual", void 0);
+    _defineProperty(this, "expected", void 0);
+    _defineProperty(this, "operator", void 0);
+    _defineProperty(this, "showDiff", void 0);
+    _defineProperty(this, "name", 'EnsureError');
+    this.actual = actual;
+    this.expected = expected;
+    this.operator = operator;
+    this.showDiff = showDiff;
+    Error.captureStackTrace(this, ensure); // the stack starts at the test's ensure() call
+  }
+}
+function ensure(tree, facts, options = {}) {
+  const sightings = contentSightings(tree);
+  const miss = check(sightings, facts);
+  if (miss === undefined) return;
+  const [fact, failure] = miss;
+  const {
+    readable = true,
+    color = process.stdout.isTTY && process.stdout.hasColors()
+  } = options;
+  const style = {
+    readable,
+    paint: color ? (tint, text) => styleText(tint, text, {
+      validateStream: false
+    }) : (_, text) => text
+  };
+  const message = `expected ${readable ? fact.spoken : fact.chained}, ${failure.saw}`
+  // the · holds the gap until sxy-test-runner keeps blank lines
+  + (readable ? `\n  rule: ${fact.chained}\n  ·` : '') + `\n  ${seenLine(fact, sightings, style, true)}`;
+  const {
+    actual,
+    expected,
+    showDiff
+  } = failure;
+  throw new EnsureError(message, actual, expected, fact.operator, showDiff);
+}
+// each fact started and told of its sightings, ready to decide
+function tracked(sightings, facts) {
+  const started = buildFacts(facts);
+  const byKind = new Map();
+  for (const fact of started) byKind.set(fact.kind, [...(byKind.get(fact.kind) ?? []), fact]);
+  for (const [kind, value] of sightings) {
+    for (const fact of byKind.get(kind) ?? []) fact.track(fact.test(value));
+  }
+  return started;
+}
+const ofKind = (sightings, kind) => sightings.filter(([seenKind]) => seenKind === kind).length;
+// the first fact to fail, with what it saw.
+// Every fact decides, including those of a kind the tree never showed
+function check(sightings, facts) {
+  for (const fact of tracked(sightings, facts)) {
+    const failure = fact.decide(ofKind(sightings, fact.kind));
+    if (failure !== undefined) return [fact, failure];
+  }
+  return undefined;
+}
+// matching: whether a sighting meets a scope's inner facts, stopping at the first miss
+const scopeTest = (scopeOf, inner) => seen => {
+  const sightings = scopeOf(seen);
+  return sightings !== undefined && check(sightings, inner) === undefined;
+};
+// reporting, once a fact has failed: every inner fact a sighting missed and met.
+// Its score: 2 for each fact met, 1 for each missed whose kind it holds
+const scopeExplain = (scopeOf, inner) => seen => {
+  const sightings = scopeOf(seen);
+  if (sightings === undefined) return 'not content';
+  const misses = [];
+  const met = [];
+  let score = 0;
+  for (const fact of tracked(sightings, inner)) {
+    const seenOfKind = ofKind(sightings, fact.kind);
+    const failure = fact.decide(seenOfKind);
+    if (failure === undefined) {
+      score += 2;
+      met.push(fact);
+    } else {
+      if (seenOfKind > 0) score += 1;
+      misses.push({
+        fact,
+        failure,
+        sightings
+      });
+    }
+  }
+  return misses.length === 0 ? undefined : {
+    misses,
+    met,
+    score
+  };
+};
+// a scoped inner fact lists its own sightings with their reasons, down to the miss;
+// its description would only repeat the rest of the outer one
+function explained(outcome, style) {
+  const {
+    readable,
+    paint
+  } = style;
+  if (outcome === 'not content') return paint('red', outcome);
+  const label = fact => readable ? fact.spoken : fact.chained;
+  const missed = outcome.misses.map(({
+    fact,
+    failure,
+    sightings
+  }) => {
+    if (fact.explain === undefined) return paint('red', `${label(fact)}: ${failure.saw}`);
+    // a children fact's one sighting is its element, so listing it would repeat the element
+    const element = fact.operator === '' ? sightings.find(([kind]) => kind === fact.kind) : undefined;
+    const inner = element === undefined ? undefined : fact.explain(element[1]);
+    if (inner !== undefined) {
+      return `${readable ? 'in its children,' : 'children:'} ${explained(inner, style)}`;
+    }
+    return `${paint('red', `${failure.saw};`)} ${seenLine(fact, sightings, style)}`;
+  });
+  const met = outcome.met.length === 0 ? [] : [paint('green', `met: ${outcome.met.map(label).join(', ')}`)];
+  return [...missed, ...met].join('; ');
+}
+// met: first; not content: last
+const rank = outcome => outcome === undefined ? Infinity : outcome === 'not content' ? -1 : outcome.score;
+const fnName = fn => fn.name === '' ? 'fn' : fn.name;
+// a fact as it reads inside a scope: one.prop('href'); a children fact carries no quantifier
+const chained = ([,,, quantifier, end]) => quantifier === '' ? end : `${quantifier}.${end}`;
+const listed = facts => `[${facts.map(chained).join(', ')}]`;
+const childrenKind = 'children';
+// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+const childrenScope = seen => contentSightings(seen.children);
+// a children fact takes the kind of the element whose with list holds it
+const forKind = (fact, kind) => fact[0] === childrenKind ? [kind, fact[1], fact[2], fact[3], fact[4], fact[5], fact[6]] : fact;
+// a with list holds one sighting of its element's kind - the element itself - so a children fact
+// passes where the element's content meets its inner facts
+function childrenFact(inner, end, spoken) {
+  return [childrenKind, scopeTest(childrenScope, inner), counting(count => count === 1, 1), '', end, `${spoken} in its children`, scopeExplain(childrenScope, inner)];
+}
+// the element's children as a tree, for a with list, beside the element's own facts:
+// with([one.className('x'), children.one.html('li')]), or with([children([…])]) for a list of them
+export const children = withMembers(facts => childrenFact(facts, `children(${listed(facts)})`, spokenList(facts)), quantifiers(inner => childrenFact([inner], `children.${chained(inner)}`, inner[5])));
+function withMembers(fn, members) {
+  Object.defineProperties(fn, Object.getOwnPropertyDescriptors(members));
+  return fn; // eslint-disable-line @typescript-eslint/no-unsafe-type-assertion
+}
+// each fact's requirement started for this run, with its own state
+function buildFacts(facts) {
+  return facts.map(fact => {
+    const [kind, test, requirement, quantifier,, spoken, explain] = fact;
+    const [track, decide] = requirement();
+    return {
+      kind,
+      test,
+      track,
+      decide,
+      explain,
+      spoken,
+      chained: chained(fact),
+      operator: quantifier
+    };
+  });
+}
+const countFailure = (actual, expected) => ({
+  actual,
+  expected,
+  saw: `saw ${actual}`,
+  showDiff: true
+});
+// counts every match, so a failure reports the full count, not the one it stopped at
+function counting(pass, expected) {
+  return () => {
+    let count = 0;
+    return [match => {
+      if (match) ++count;
+    }, () => pass(count) ? undefined : countFailure(count, expected)];
+  };
+}
+const seenListed = 10;
+// only those listed are shown, as a nested reason is costly to build
+function listing(items, show, separator = ', ') {
+  return items.slice(0, seenListed).map(show).join(separator) + (items.length > seenListed ? `${separator}… ${items.length - seenListed} more` : '');
+}
+// each sighting with why it missed, where the fact can say, the nearest first;
+// none of an element kind seen: list the other tags or components, as a near miss.
+// Top level elements a line each, as their props and reasons run long; nested ones stay inline
+function seenLine({
+  kind,
+  explain
+}, sightings, style, top = false) {
+  const {
+    readable,
+    paint
+  } = style;
+  const separator = top && /^(html|component):/.test(kind) ? '\n    ' : ', ';
+  const named = readable ? spokenKind(kind) : kind;
+  const seen = sightings.filter(([seenKind]) => seenKind === kind).map(sighting => ({
+    sighting,
+    outcome: explain?.(sighting[1])
+  }));
+  if (seen.length > 0) {
+    // stable, so sightings as near as each other stay in document order
+    if (explain !== undefined) seen.sort((a, b) => rank(b.outcome) - rank(a.outcome));
+    const opening = separator === ', ' ? ' ' : separator;
+    const shown = listing(seen, ({
+      sighting,
+      outcome
+    }) => paint('white', displaySighting(sighting)) + (outcome === undefined ? '' : ` (${explained(outcome, style)})`), separator);
+    const heading = readable && seen.length > 1 ? plural(named) : named;
+    return `${paint('white', `${heading} seen:`)}${opening}${shown}`;
+  }
+  const family = /^(html|component):/.exec(kind)?.[1];
+  if (family === undefined) return `no ${named} seen`;
+  const others = sightings.filter(([seenKind]) => seenKind.startsWith(`${family}:`)).map(([seenKind]) => seenKind.slice(family.length + 1));
+  return others.length === 0 ? `no ${named} seen` : `no ${named} seen; ${family} seen: ${listing(others, name => name)}`;
+}
+// <button>s, title props, classes
+const plural = named => named.endsWith('s') ? `${named}es` : `${named}s`;
+// a kind as prose: <button>, title prop, element text
+function spokenKind(kind) {
+  const [family, name] = kind.split(/:(.*)/);
+  if (family === 'html' || family === 'component') return `<${name}>`;
+  if (family === 'prop') return `${name} prop`;
+  const plain = {
+    text: 'text node',
+    interruptedText: 'element text',
+    className: 'class'
+  };
+  return plain[kind] ?? kind;
+}
+// an element as its tag or name and props, as written: <a href='/x'>
+function displaySighting([kind, value]) {
+  if (kind === 'fragment') return '<>';
+  const element = /^(?:html|component):(.*)$/.exec(kind)?.[1];
+  if (element === undefined) return display(value);
+  const props = Object.entries(value).filter(([name]) => name !== 'children').map(([name, prop]) => ` ${name}=${display(prop)}`);
+  return `<${element}${props.join('')}>`;
+}
+const displayed = 5; // entries shown of an array or object
+const displayDepth = 2;
+// a value as a failure message shows it; arrays and objects shortened by length and depth
+function display(value, depth = 0) {
+  if (typeof value === 'string') return `'${value}'`;
+  if (typeof value === 'function') {
+    return value.name === '' ? '[function]' : `[function ${value.name}]`;
+  }
+  if (typeof value !== 'object' || value === null) {
+    return String(value); // a number, boolean, bigint, symbol, null or undefined
+  }
+  if (value instanceof Date) {
+    return isNaN(value.getTime()) ? 'Date(invalid)' : `Date(${value.toISOString()})`;
+  }
+  // an element held as a value, as in a prop: by tag or name, as its symbol keys hide it as data
+  if ($type in value && IsContentNode(value) && ContentNodeIsElement(value)) {
+    const type = value[$type];
+    if (type === $fragment) return '<>';
+    return `<${typeof type === 'string' ? type : componentTypeIdentityKey(type)}>`;
+  }
+  const shown = entries => depth >= displayDepth ? '…' : entries.slice(0, displayed).join(', ') + (entries.length > displayed ? ', …' : '');
+  if (Array.isArray(value)) {
+    return value.length === 0 ? '[]' : `[${shown(value.map(each => display(each, depth + 1)))}]`;
+  }
+  if (value instanceof Set) {
+    return `Set { ${shown([...value].map(each => display(each, depth + 1)))} }`;
+  }
+  if (value instanceof Map) {
+    const pairs = [...value].map(([key, each]) => `${display(key, depth + 1)} => ${display(each, depth + 1)}`);
+    return `Map { ${shown(pairs)} }`;
+  }
+  const entries = Object.entries(value).map(([key, each]) => `${key}: ${display(each, depth + 1)}`);
+  return entries.length === 0 ? '{}' : `{ ${shown(entries)} }`;
+}
+// an element's edge: text either side of one is not one run of text
+const edge = Symbol('edge');
+// in document order; the unrendered tree: a component is seen by name, its content not expanded.
+// Adjacent text is one sighting, as the page shows it: JSX splits `Hi, {name}.` into three
+function contentSightings(content) {
+  const sightings = [];
+  let run; // the text sighting still open to joining
+  for (const token of contentTokens(content)) {
+    if (token === edge) run = undefined;
+    // a fragment is seen but is no break, as it renders nothing of its own
+    else if (token[0] === 'fragment') sightings.push([...token]);else if (token[0] === 'text') {
+      if (run === undefined) {
+        run = ['text', token[1]];
+        sightings.push(run);
+      } else run[1] += token[1];
+    } else {
+      run = undefined;
+      sightings.push([...token]);
+    }
+  }
+  return sightings;
+}
+// fragments, arrays and non-rendered values add no edge: their text runs on into their neighbours'
+function contentTokens(content) {
+  if (ContentNodeIsArray(content)) return content.flatMap(contentTokens);
+  if (ContentNodeIsLiteral(content)) return [['text', String(content)]];
+  if (!ContentNodeIsElement(content)) return []; // null, undefined, boolean
+  const props = content[$props];
+  if (ContentNodeElementIsHtml(content)) {
+    const descendants = contentTokens(props.children);
+    return [edge, ...htmlOwnSightings(content[$type], props), ...descendants, edge];
+  }
+  if (ContentNodeElementIsComponent(content)) {
+    // the name stylesheets match by
+    const name = componentTypeIdentityKey(content[$type]);
+    /// TODO children is a prop the component may render or not, so the walk arguably should
+    /// stop here and leave what it holds to children() - but too much breaks without it for now
+    return [edge, ...componentOwnSightings(name, props), ...contentTokens(props.children), edge];
+    /// TODO components can have classNames, ids too...
+  }
+  const fragment = ['fragment', props]; // seen, but unwrapped: its content is walked
+  return [fragment, ...contentTokens(props.children)];
+}
+// an element's sightings of itself, its content left out
+function htmlOwnSightings(tag, props) {
+  // class and id only on html: a component's className is still a prop, not a class
+  const classes = props.className ?? props.class;
+  const classNames = typeof classes === 'string' ? classes.split(/\s+/).filter(c => c !== '') : [];
+  const id = typeof props.id === 'string' ? [['id', props.id]] : [];
+  const text = contentText(props.children);
+  const interrupted = text === '' ? [] : [['interruptedText', text]];
+  return [[`html:${tag}`, props], ...classNames.map(c => ['className', c]), ...id, ...interrupted, ...propSightings(props)];
+}
+// an element's whole text, the markup between the words ignored, as textContent reads it.
+// A component's children count, as the walk takes them: the two say the same about a tree
+function contentText(content) {
+  if (ContentNodeIsArray(content)) return content.map(contentText).join('');
+  if (ContentNodeIsLiteral(content)) return String(content);
+  if (!ContentNodeIsElement(content)) return ''; // null, undefined, boolean
+  return contentText(content[$props].children);
+}
+function componentOwnSightings(name, props) {
+  return [[`component:${name}`, props], ...propSightings(props)];
+}
+const lower = text => text.toLowerCase();
+// g and y would carry lastIndex from one sighting's test to the next, so they are dropped
+function matching(regex, addFlags = '') {
+  const flags = [...new Set(regex.flags.replace(/[gy]/g, '') + addFlags)].join('');
+  const plain = new RegExp(regex.source, flags);
+  return seen => typeof seen === 'string' && plain.test(seen);
+}
+// subset: chai-subset's containSubset, but a function in the shape is compared by reference, not
+// called: extra keys and array elements pass, each shape element matching some element, any order.
+// duck: as TS structural typing - extra keys pass, but an array is a tuple: same length, in place.
+// Beyond chai-subset: Object.is, as deep-eql, so NaN matches; Map and Set shapes are subsets too.
+// As chai-subset: a key undefined in the shape matches a missing one
+function contains(shape, value, arrays) {
+  const within = (inner, seen) => contains(inner, seen, arrays);
+  if (Object.is(shape, value)) return true;
+  if (typeof shape !== 'object' || shape === null) return false;
+  if (typeof value !== 'object' || value === null) return false;
+  const someOf = (values, each) => values.some(seen => within(each, seen));
+  if (Array.isArray(shape)) {
+    if (!('length' in value) || typeof value.length !== 'number') return false;
+    const values = Array.from(value);
+    return arrays === 'inPlace' ? shape.length === values.length && shape.every((each, i) => within(each, values[i])) : shape.every(each => someOf(values, each));
+  }
+  if (shape instanceof Date) {
+    return value instanceof Date && Object.is(shape.getTime(), value.getTime());
+  }
+  if (shape instanceof Set) {
+    return value instanceof Set && [...shape].every(each => someOf([...value], each));
+  }
+  if (shape instanceof Map) {
+    return value instanceof Map && [...shape].every(([key, each]) => value.has(key) && within(each, value.get(key)));
+  }
+  const record = value;
+  return Object.entries(shape).every(([key, each]) => within(each, record[key]));
+}
+// every prop but children, whose content is walked instead
+function propSightings(props) {
+  return Object.entries(props).filter(([name]) => name !== 'children').map(([name, value]) => [`prop:${name}`, value]);
+}

package/dist/testing/ensure.trial.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ensure.trial.d.ts.map

package/dist/testing/ensure.trial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure.trial.d.ts","sourceRoot":"","sources":["../../src/testing/ensure.trial.ts"],"names":[],"mappings":""}

package/dist/testing/ensure.trial.js

@@ -0,0 +1,9 @@
+import { $props, $type } from '../contentNodeSymbols.js';
+import { ensure } from './ensure.js';
+const content = {
+  [$type]: 'span',
+  [$props]: {
+    children: 'Bob'
+  }
+};
+ensure(content, [ensure.one.text('Bob'), ensure.one.text.contains('o'), ensure.one.prop('to').is('foo')]);

package/dist/testing/helpers/contentHtmlElements.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contentHtmlElements.d.ts","sourceRoot":"","sources":["../../../src/testing/helpers/contentHtmlElements.ts"],"names":[],"mappings":"AAEA,OAAO,EAGH,KAAK,WAAW,EAChB,KAAK,eAAe,EACvB,MAAM,sBAAsB,CAAA;AAG7B,eAAO,MAAM,mBAAmB,GAAI,SAAS,WAAW,KAAG,eAAe,EAUzE,CAAA"}
+{"version":3,"file":"contentHtmlElements.d.ts","sourceRoot":"","sources":["../../../src/testing/helpers/contentHtmlElements.ts"],"names":[],"mappings":"AAEA,OAAO,EACH,KAAK,WAAW,EAAE,KAAK,eAAe,EAEzC,MAAM,sBAAsB,CAAA;AAG7B,eAAO,MAAM,mBAAmB,GAAI,SAAS,WAAW,KAAG,eAAe,EAUzE,CAAA"}