tungsten 0.6.3 → 0.7.1

package/dist/testing/ensure.js

@@ -0,0 +1,664 @@
+function _classPrivateFieldInitSpec(e, t, a) { _checkPrivateRedeclaration(e, t), t.set(e, a); }
+function _checkPrivateRedeclaration(e, t) { if (t.has(e)) throw new TypeError("Cannot initialize the same private elements twice on an object"); }
+function _classPrivateFieldSet(s, a, r) { return s.set(_assertClassBrand(s, a), r), r; }
+function _classPrivateFieldGet(s, a) { return s.get(_assertClassBrand(s, a)); }
+function _assertClassBrand(e, t, n) { if ("function" == typeof e ? e === t : e.has(t)) return arguments.length < 3 ? t : n; throw new TypeError("Private element is not present on this object"); }
+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 { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { styleText } from 'node:util';
+import deepEqual from 'deep-eql';
+import { warn } from '../output.js';
+import { ContentNodeElementIsComponent, ContentNodeElementIsHtml, ContentNodeIsArray, ContentNodeIsElement, ContentNodeIsLiteral, IsContentNode } from '../ContentNode.js';
+import { $props, $type } from '../contentNodeSymbols.js';
+import { componentTypeIdentityKey } from '../hmr/componentIdentity.js';
+import { display } from './display.js';
+// with: the match's properties; its tag, and text and elements it holds, are for children
+const propertyEnds = ['interruptedText', 'className', 'id', 'prop'];
+// 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;
+// E: the ends as the caller offers them, which the built ends are typed loosely for.
+// properties: only the ends a with list takes
+function quantifiers(finish, properties = false) {
+  const made = (quantifier, requirement, spoken) => {
+    const all = ends(quantifier, requirement, finish, spoken);
+    const offered = properties ? Object.fromEntries(propertyEnds.map(name => [name, all[name]])) : all;
+    return offered; // eslint-disable-line @typescript-eslint/no-unsafe-type-assertion
+  };
+  return {
+    get no() {
+      return made('no', counting(count => count === 0, 0));
+    },
+    get none() {
+      return made('none', counting(count => count === 0, 0), 'no');
+    },
+    get one() {
+      return made('one', counting(count => count === 1, 1));
+    },
+    get two() {
+      return made('two', counting(count => count === 2, 2));
+    },
+    get three() {
+      return made('three', counting(count => count === 3, 3));
+    },
+    get a() {
+      return made('a', counting(count => count === 1, 1));
+    },
+    get an() {
+      return made('an', counting(count => count === 1, 1));
+    },
+    count: num => made(`count(${num})`, counting(count => count === num, num), String(num)),
+    get some() {
+      return made('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
+        }];
+      });
+    },
+    // every sighting of its kind must match, and there must be one: all of none proves nothing
+    get all() {
+      return made('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
+        }];
+      }, '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.
+// Typed loosely, every end making a plain Fact; quantifiers() gives them their offered types
+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, own);
+    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(propsOf(seen)), `${end}.with(${fnName(facts)})`, `${prose} passing ${fnName(facts)}`), quantifiers(inner => within([inner], `with.${chained(inner)}`, `with ${inner[5]}`), true)), {
+        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}>`, seen => htmlOwnSightings(tag, propsOf(seen))),
+    component: name => element(`component:${name}`, `component('${name}')`, `<${name}>`, seen => componentOwnSightings(name, propsOf(seen))),
+    select: query => {
+      selector(query); // an invalid selector throws here, as the fact is made
+      return element(`select:${query}`, `select('${query}')`, `'${query}' ${noun('element')}`, selectOwnSightings);
+    },
+    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));
+  }
+  for (const [kind, kindFacts] of byKind) {
+    if (!isSelectKind(kind)) continue;
+    for (const [, value] of selectSightings(sightings, kind)) {
+      for (const fact of kindFacts) fact.track(fact.test(value));
+    }
+  }
+  return started;
+}
+const isSelectKind = kind => kind.startsWith('select:');
+const sightingsOf = (sightings, kind) => isSelectKind(kind) ? selectSightings(sightings, kind) : sightings.filter(([seenKind]) => seenKind === kind);
+const ofKind = (sightings, kind) => sightingsOf(sightings, 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 === '' ? sightingsOf(sightings, fact.kind)[0] : 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';
+const childrenScope = seen => contentSightings(propsOf(seen).children);
+// an element sighting's value is its props, or for a selector's, the element it matched
+const propsOf = seen =>
+// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+seen instanceof SelectElement ? seen.props : seen;
+// 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) {
+  const fact = [childrenKind, scopeTest(childrenScope, inner), counting(count => count === 1, 1), '', end, `${spoken} in its children`, scopeExplain(childrenScope, inner)];
+  return fact; // eslint-disable-line @typescript-eslint/no-unsafe-type-assertion
+}
+// 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|select):/.test(kind) ? '\n    ' : ', ';
+  const named = readable ? spokenKind(kind) : kind;
+  const seen = sightingsOf(sightings, 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 === 'select') return `'${name}' element`;
+  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 '<>';
+  if (value instanceof SelectElement) return displayElement(value.name, value.props);
+  const element = /^(?:html|component):(.*)$/.exec(kind)?.[1];
+  return element === undefined ? display(value) : displayElement(element, value);
+}
+function displayElement(element, props) {
+  const shown = Object.entries(props).filter(([name]) => name !== 'children').map(([name, prop]) => ` ${name}=${display(prop)}`);
+  return `<${element}${shown.join('')}>`;
+}
+// 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]);
+    }
+  }
+  sightings.push(['elements', {
+    roots: selectNodes(content, null),
+    descend: true
+  }]);
+  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]);
+}
+// an element as a selector reads it; a component, by name, is the parent of what it holds.
+// Each scope is a tree of its own, so a selector sees no ancestor outside it
+var _children = /*#__PURE__*/new WeakMap();
+class SelectElement {
+  constructor(family, name, props, parent, siblings) {
+    _defineProperty(this, "family", void 0);
+    _defineProperty(this, "name", void 0);
+    _defineProperty(this, "props", void 0);
+    _defineProperty(this, "parent", void 0);
+    _defineProperty(this, "siblings", void 0);
+    _classPrivateFieldInitSpec(this, _children, void 0);
+    this.family = family;
+    this.name = name;
+    this.props = props;
+    this.parent = parent;
+    this.siblings = siblings;
+  }
+  get children() {
+    return _classPrivateFieldGet(_children, this) ?? _classPrivateFieldSet(_children, this, selectNodes(this.props.children, this));
+  }
+}
+// fragments and arrays unwrapped, as the page has no node for them
+function selectNodes(content, parent) {
+  const nodes = [];
+  const add = each => {
+    if (ContentNodeIsArray(each)) each.forEach(add);else if (ContentNodeIsLiteral(each)) nodes.push(String(each));else if (!ContentNodeIsElement(each)) return; // null, undefined, boolean
+    else if (ContentNodeElementIsHtml(each)) {
+      nodes.push(new SelectElement('html', each[$type], each[$props], parent, nodes));
+    } else if (ContentNodeElementIsComponent(each)) {
+      const name = componentTypeIdentityKey(each[$type]);
+      nodes.push(new SelectElement('component', name, each[$props], parent, nodes));
+    } else add(each[$props].children);
+  };
+  add(content);
+  return nodes;
+}
+// its own sightings, and itself to match: a children fact in its with list is of its kind.
+// It keeps its place in the tree, so an ancestor in the selector still holds
+const selectOwnSightings = seen => {
+  const element = seen; // eslint-disable-line @typescript-eslint/no-unsafe-type-assertion
+  const {
+    family,
+    name,
+    props
+  } = element;
+  const own = family === 'html' ? htmlOwnSightings(name, props) : componentOwnSightings(name, props);
+  return [...own, ['elements', {
+    roots: [element],
+    descend: false
+  }]];
+};
+function selectSightings(sightings, kind) {
+  const matches = selector(kind.slice('select:'.length));
+  const found = [];
+  const visit = (nodes, descend) => {
+    for (const node of nodes) {
+      if (typeof node === 'string') continue;
+      if (matches(node)) found.push([kind, node]);
+      if (descend) visit(node.children, true);
+    }
+  };
+  for (const [seenKind, value] of sightings) {
+    if (seenKind !== 'elements') continue;
+    const {
+      roots,
+      descend
+    } = value; // eslint-disable-line @typescript-eslint/no-unsafe-type-assertion
+    visit(roots, descend);
+  }
+  return found;
+}
+const selectors = new Map();
+// on the first select(): ~100ms and 44 modules at import, which no other fact needs
+let cssSelect;
+// shipped in the package's vendor/, as dist is
+export const cssSelectBundle = fileURLToPath(new URL('../../vendor/css-select.js', import.meta.url));
+// the vendor bundle (one file, ~9ms), else the package (44 modules, ~100ms)
+function loadCssSelect() {
+  const bundled = existsSync(cssSelectBundle);
+  if (!bundled) {
+    warn(`tungsten ensure: no css-select bundle at ${cssSelectBundle}; ` + 'loading the package instead, which is slower');
+  }
+  const load = createRequire(import.meta.url);
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  return load(bundled ? cssSelectBundle : 'css-select');
+}
+function selector(query) {
+  let compiled = selectors.get(query);
+  if (compiled === undefined) {
+    cssSelect ??= loadCssSelect();
+    // xmlMode: names as written, so Link is a component and link no tag
+    compiled = cssSelect.compile(query, {
+      adapter,
+      xmlMode: true,
+      cacheResults: false
+    });
+    selectors.set(query, compiled);
+  }
+  return compiled;
+}
+// as the page renders it: true present and empty; false, null and undefined absent.
+// class and id only on html, as a component's className is still a prop
+function attribute({
+  family,
+  props
+}, name) {
+  const html = family === 'html';
+  if (name === 'children' || !html && (name === 'class' || name === 'id')) return undefined;
+  const value = !html ? props[name] : name === 'class' ? props.className ?? props.class : name === 'for' ? props.htmlFor ?? props.for : props[name];
+  if (value === undefined || value === null || value === false) return undefined;
+  if (value === true) return '';
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'bigint') return String(value);
+  return ''; // a handler or data: present, with no text to compare
+}
+function hasAncestorIn(node, nodes) {
+  for (let up = typeof node === 'string' ? null : node.parent; up !== null; up = up.parent) {
+    if (nodes.includes(up)) return true;
+  }
+  return false;
+}
+const adapter = {
+  isTag: node => typeof node !== 'string',
+  getName: element => element.name,
+  getParent: element => element.parent,
+  getChildren: node => typeof node === 'string' ? [] : node.children,
+  getSiblings: node => typeof node === 'string' ? [node] : node.siblings,
+  getText: node => typeof node === 'string' ? node : contentText(node.props.children),
+  getAttributeValue: attribute,
+  hasAttrib: (element, name) => attribute(element, name) !== undefined,
+  removeSubsets: nodes => nodes.filter((node, i) => nodes.indexOf(node) === i && !hasAncestorIn(node, nodes))
+};

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":""}