@gjsify/unit 0.52.0 → 0.54.0

package/README.md

@@ -36,6 +36,15 @@ gjs -m test.gjs.js
 node test-runner.mjs
 ```
 
+### Capability gates in CI
+
+`on('Display')` and `on('Gl')` run their block only where the host can realize a surface / a
+GL context — `on('Gl')` asks by realizing a GDK GL context once per process. A "no" is a skip,
+which is right on a host without GL and wrong on a CI step that provisioned it. Such a step sets
+`GJSIFY_TEST_EXPECT_AXES=Gl` (comma-separated axes): an expected axis that a gate named but the
+host did not match then fails the run, with the probe's reason. An entry that never names the
+axis is not held to it.
+
 ### Available matchers
 
 - `toBe(value)` — strict equality (`===`)

package/lib/esm/capabilities.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";function isDisplaylessBackend(e){return e===`win32`||e===`darwin`}function canRealizeSurface(e,t){return isDisplaylessBackend(e)||!!(t.DISPLAY||t.WAYLAND_DISPLAY)}function canRealizeGl(e,t){return e===`linux`&&!!(t.DISPLAY||t.WAYLAND_DISPLAY)}export{canRealizeGl,canRealizeSurface,isDisplaylessBackend};
+import"./_virtual/_rolldown/runtime.js";function isDisplaylessBackend(e){return e===`win32`||e===`darwin`}function canRealizeSurface(e,t){return isDisplaylessBackend(e)||!!(t.DISPLAY||t.WAYLAND_DISPLAY)}async function canRealizeGl(e,t,n){return canRealizeSurface(e,t)&&await n()}export{canRealizeGl,canRealizeSurface,isDisplaylessBackend};

package/lib/esm/index.js

@@ -6,9 +6,9 @@ import"./_virtual/_rolldown/runtime.js";import{canRealizeGl as e,canRealizeSurfa
       Expected: ${formatValue(e)} (${typeof e})\n      Actual: ${formatValue(this.actualValue)} (${typeof this.actualValue})`)}toBeInstanceOf(e){this.triggerResult(this.actualValue instanceof e,`      Expected value to be instance of ${e.name||e}\n      Actual: ${this.actualValue?.constructor?.name||typeof this.actualValue}`)}toHaveLength(e){let t=this.actualValue?.length;this.triggerResult(t===e,`      Expected length: ${e}\n      Actual length: ${t}`)}toMatch(e){let t=this.actualValue;if(typeof t.match!=`function`)throw Error(`You can not use toMatch on type ${typeof this.actualValue}`);this.triggerResult(!!t.match(e),`      Expected values to match using regular expression
       Expression: `+formatValue(e)+`
       Actual: `+formatValue(this.actualValue))}toBeDefined(){this.triggerResult(this.actualValue!==void 0,`      Expected value to be defined`)}toBeUndefined(){this.triggerResult(this.actualValue===void 0,`      Expected value to be undefined`)}toBeNull(){this.triggerResult(this.actualValue===null,`      Expected value to be null`)}toBeTruthy(){this.triggerResult(this.actualValue,`      Expected value to be truthy`)}toBeFalsy(){this.triggerResult(!this.actualValue,`      Expected value to be falsy`)}toBeNaN(){this.triggerResult(Number.isNaN(this.actualValue),`      Expected value to be NaN\n      Actual: ${formatValue(this.actualValue)}`)}toContain(e){let t=this.actualValue,n;n=typeof t==`string`?t.includes(String(e)):t instanceof Array?t.indexOf(e)!==-1:!1,this.triggerResult(n,`      Expected `+formatValue(t)+` to contain `+formatValue(e))}toBeLessThan(e){this.triggerResult(this.actualValue<e,`      Expected `+formatValue(this.actualValue)+` to be less than `+e)}toBeGreaterThan(e){this.triggerResult(this.actualValue>e,`      Expected `+formatValue(this.actualValue)+` to be greater than `+e)}toBeGreaterThanOrEqual(e){this.triggerResult(this.actualValue>=e,`      Expected ${formatValue(this.actualValue)} to be greater than or equal to ${e}`)}toBeLessThanOrEqual(e){this.triggerResult(this.actualValue<=e,`      Expected ${formatValue(this.actualValue)} to be less than or equal to ${e}`)}toBeCloseTo(e,t){let n=10**t;this.triggerResult(Math.round(this.actualValue*n)/n===Math.round(e*n)/n,`      Expected `+formatValue(this.actualValue)+` with precision `+t+` to be close to `+e)}toThrow(e){let t=``,n=!1,r=!0,i=!0,a=this.actualValue;try{a(),n=!1}catch(a){t=a?.message||``,n=!0,forgetThrownAssertion(a),typeof e==`function`?r=a instanceof e:typeof e==`string`?i=t.includes(e):e instanceof RegExp&&(i=e.test(t))}let o=this.actualValue?.name||typeof this.actualValue==`function`?`[anonymous function]`:String(this.actualValue);this.triggerResult(n,`      Expected ${o} to ${this.positive?`throw`:`not throw`} an exception ${!this.positive&&t?`, but an error with the message "${t}" was thrown`:``}`),typeof e==`function`?this.triggerResult(r,`      Expected Error type '${e.name}', but the error is not an instance of it`):e!==void 0&&this.triggerResult(i,`      Expected error message to match ${e}\n      Actual message: "${t}"`)}async toReject(e){let t=!1,n=``,r=!0,i=!0;try{await this.actualValue,t=!1}catch(a){t=!0,forgetThrownAssertion(a),n=a?.message||String(a),typeof e==`function`?r=a instanceof e:typeof e==`string`?i=n.includes(e):e instanceof RegExp&&(i=e.test(n))}this.triggerResult(t,`      Expected promise to ${this.positive?`reject`:`resolve`}${!this.positive&&n?`, but it rejected with "${n}"`:``}`),t&&typeof e==`function`?this.triggerResult(r,`      Expected rejection type '${e.name}', but the error is not an instance of it`):t&&e!==void 0&&this.triggerResult(i,`      Expected rejection message to match ${e}\n      Actual message: "${n}"`)}async toResolve(){let e=!1,t=``;try{await this.actualValue,e=!0}catch(n){e=!1,forgetThrownAssertion(n),t=n?.message||String(n)}this.triggerResult(e,`      Expected promise to ${this.positive?`resolve`:`reject`}${e?``:`, but it rejected with "${t}"`}`)}get rejects(){return{toThrow:e=>this.toReject(e),toReject:e=>this.toReject(e)}}get resolves(){return{toResolve:()=>this.toResolve()}}};const describe=async function(e,t,n){let r=typeof n==`number`?n:n?.timeout??k.suiteTimeout;z(`
-`+e);let i=E;E=e;let a=now();W.push({before:[],after:[]});try{await withTimeout(t,r,`describe: ${e}`)}catch(t){if(t instanceof TimeoutError)++m,O.push({suite:e,test:`<suite timed out>`,message:t.message}),z(`  ${P}⏱ Suite timed out: ${t.message}${R}`);else throw t}finally{W.pop()}E=i;let o=now()-a;z(`  ${L}↳ ${formatDuration(o)}${R}`)};describe.skip=async function(e,t){++h,z(`\n${I}- ${e} (skipped)${R}`)};const envVar=e=>{let t=runtimeGlobals().process?.env;if(t)return t[e];let n=runtimeGlobals().imports?.gi?.GLib;return n?n.getenv(e)??void 0:void 0},displayEnv=()=>({DISPLAY:envVar(`DISPLAY`),WAYLAND_DISPLAY:envVar(`WAYLAND_DISPLAY`)}),hasDisplay=()=>t(s(),displayEnv()),hasGl=()=>e(s(),displayEnv()),runtimeMatch=async function(e,t){if(e.includes(`Display`))return{matched:hasDisplay(),runtime:`Display`};if(e.includes(`Gl`))return{matched:hasGl(),runtime:`Gl`};let n=await getRuntime(),r=e.find(e=>n.includes(e));return!r||typeof t==`string`&&!n.includes(t)?{matched:!1}:{matched:!0,runtime:r,version:t}},on=async function(e,t,n){typeof e==`string`&&(e=[e]),typeof t==`function`&&(n=t,t=void 0);let{matched:r,runtime:i}=await runtimeMatch(e,t);if(!r){++h;for(let t of e)++axisRecord(t).ignored;return}z(`\nOn ${e.join(`, `)}${t?` `+t:``}`);let a=d;await n();let o=axisRecord(i??e[0]);++o.matched,o.tests+=d-a},W=[{before:[],after:[]}],currentHookFrame=()=>W[W.length-1],beforeEach=function(e){typeof e==`function`&&currentHookFrame().before.push(e)},afterEach=function(e){typeof e==`function`&&currentHookFrame().after.push(e)},runBeforeEachHooks=async()=>{for(let e of W)for(let t of e.before)await t()},runAfterEachHooks=async()=>{for(let e=W.length-1;e>=0;--e){let t=W[e];for(let e=t.after.length-1;e>=0;--e)await t.after[e]()}},it=async function(e,t,n){let r=j.get(e);if(r!==void 0){++h,z(`  ${I}-${R} ${L}${e} (skipped: ${r})${R}`);return}let i=typeof n==`number`?n:n?.timeout??k.testTimeout,a=now();++d,++y,D=e;let o=new Set;C.push(o);let s,c=!1;try{await runBeforeEachHooks(),A.noteInFlight(E?`${E} › ${e}`:e,i),await withTimeout(t,i,e)}catch(e){c=!0,s=e,e instanceof Error&&o.delete(e)}finally{try{await runAfterEachHooks()}catch(t){c?noteWarning(`afterEach also threw while "${e}" was already failing: ${errorMessage(t)}`):(c=!0,s=t,t instanceof Error&&o.delete(t))}--y,C.pop(),noteIfCwdDestroyed(e),A.noteSettled()}let l=now()-a,u=s instanceof TimeoutError?[...o]:[];if(!c){z(`  ${F}✔${R} ${L}${e}  (${formatDuration(l)})${R}`);return}++p;let m=[];c&&m.push(s?.message??String(s));for(let e of u)m.push(`${e.message}\n      ${L}↳ thrown from a callback OUTSIDE this test's awaited chain, so it could not reach the test boundary. Reject the promise from that callback (or await a helper that does) to surface it directly.${R}`);let g=m.join(`
-`),_=u[0]??s,v=c&&s instanceof TimeoutError&&u.length===0?`⏱`:`❌`;O.push({suite:E,test:e,message:g}),z(`  ${P}${v}${R} ${L}${e}  (${formatDuration(l)})${R}`),z(`${P}${g}${R}`),_?.stack&&z(_.stack)};it.skip=async function(e,t){++h,z(`  ${I}-${R} ${L}${e} (skipped)${R}`)};const getTestCounters=()=>({assertions:u,tests:d,failed:p,failedOutsideTests:m,ignored:h,xfail:_,warnings:x.length}),getAxisLedger=()=>{let e={};for(let[t,n]of v)e[t]={...n};return e};it.failing=async function(e,t,n,r){let i=typeof r==`number`?r:r?.timeout??k.testTimeout;if(typeof r==`object`&&r?.when===!1)return it(e,t,{timeout:i});let a=now();++d,++y,C.push(new Set);let o=!1;try{await runBeforeEachHooks(),await withTimeout(t,i,e)}catch{o=!0}finally{try{await runAfterEachHooks()}catch(t){noteWarning(`afterEach threw after the expected failure "${e}": ${errorMessage(t)}`)}--y,C.pop()}let s=now()-a;if(o){++_,z(`  ${I}✗${R} ${L}${e}  (expected failure — ${n})${R}`);return}++p,O.push({suite:E,test:e,message:`it.failing("${e}") PASSED — the expected failure no longer happens, so this marker is stale and must be removed (turn it back into a plain it()). It was marked expected-failing because: ${n}`}),z(`  ${P}❌${R} ${L}${e}  (${formatDuration(s)})${R}`),z(`${P}it.failing passed unexpectedly — remove the marker. Reason it carried: ${n}${R}`)};const expect=function(e,t){return++u,new U(e,!0)},failAssertion=e=>{throw e.__testFailureCounted=!0,y===0?noteStrayFailure(e?.message??String(e)):noteThrownAssertion(e),e},assert=function(e,t){++u;try{i(e,t)}catch(e){failAssertion(e)}};assert.strictEqual=function(e,t,n){++u;try{i.strictEqual(e,t,n)}catch(e){failAssertion(e)}},assert.throws=function(e,...t){++u;let n;try{e()}catch(e){n=e}try{i.throws(()=>{if(n)throw n},t[0],t[1])}catch(e){failAssertion(e)}},assert.deepStrictEqual=function(e,t,n){++u;try{i.deepStrictEqual(e,t,n)}catch(e){failAssertion(e)}};const runTests=async function(e){for(let t in e){let n=e[t];typeof n==`function`?await n():typeof n==`object`&&await runTests(n)}},browserSignalDone=()=>{let e=runtimeGlobals(),t=e.document;t&&(e.__gjsify_test_results={passed:d-p,failed:p+m,total:d,assertions:u,errors:O},t.documentElement.dataset.testsDone=`true`)},failUnexercisedAxes=async e=>{for(let t of e){let{matched:e}=await runtimeMatch([t]);if(!e)continue;let n=v.get(t);if(n&&n.tests>0)continue;++m;let r=`declared axis '${t}' ran on this host but exercised nothing — ${n?`${n.matched} gate(s) matched but executed no test, ${n.ignored} stood down`:`no on() gate named it`}`;O.push({suite:`<axis declaration>`,test:t,message:r}),z(`\n${P}❌ ${r}${R}`)}},formatFailureVerdict=e=>{let t=[];if(e.failed&&t.push(`${e.failed} of ${e.tests} tests failed`),e.outside){let n=e.outside===1?``:`s`;t.push(e.failed?`${e.outside} failure${n} outside any test`:`${e.outside} failure${n} outside any test, ${e.tests} tests passed`)}return t.join(`, and `)},exitCodeFor=(e,t)=>e>0||t?1:0,printResult=()=>{let e=T>0?now()-T:0,t=e>0?`  ${L}(${formatDuration(e)})`:``,n=w?`[${w}] `:``;if(h&&z(`\n${I}✔ ${h} ignored test${h>1?`s`:``}${R}`),v.size){z(`\n${I}⊞ axes exercised${R}`);for(let[e,t]of v)z(`  ${I}↳ ${e}: ${t.tests} test${t.tests===1?``:`s`} from ${t.matched} gate${t.matched===1?``:`s`}${t.ignored?`, ${t.ignored} stood down`:``}${R}`)}if(_&&z(`\n${I}✗ ${_} expected failure${_>1?`s`:``} (it.failing — upstream defects)${R}`),x.length){z(`\n${I}⚠ ${x.length} warning${x.length>1?`s`:``} (not counted — nothing is claimed about these)${R}`);for(let e of x)z(`  ${I}↳ ${e.message.trim().split(`
+`+e);let i=E;E=e;let a=now();K.push({before:[],after:[]});try{await withTimeout(t,r,`describe: ${e}`)}catch(t){if(t instanceof TimeoutError)++m,O.push({suite:e,test:`<suite timed out>`,message:t.message}),z(`  ${P}⏱ Suite timed out: ${t.message}${R}`);else throw t}finally{K.pop()}E=i;let o=now()-a;z(`  ${L}↳ ${formatDuration(o)}${R}`)};describe.skip=async function(e,t){++h,z(`\n${I}- ${e} (skipped)${R}`)};const envVar=e=>{let t=runtimeGlobals().process?.env;if(t)return t[e];let n=runtimeGlobals().imports?.gi?.GLib;return n?n.getenv(e)??void 0:void 0},displayEnv=()=>({DISPLAY:envVar(`DISPLAY`),WAYLAND_DISPLAY:envVar(`WAYLAND_DISPLAY`)}),hasDisplay=()=>t(s(),displayEnv());let W,G=``;const loadGlProbeGi=async()=>{let[e,t]=await Promise.all([import(`gi://Gtk?version=4.0`),import(`gi://Gdk?version=4.0`)]);if(!e.default||!t.default)throw Error(`no GTK 4 reachable from this runtime`);return{Gtk:e.default,Gdk:t.default}},realizeGlContext=async()=>{if(W!==void 0)return W;try{let{Gtk:e,Gdk:t}=await loadGlProbeGi();if(!e.init_check())throw Error(`Gtk.init_check() could not open the display`);let n=t.Display.get_default();if(!n)throw Error(`GDK has no default display`);n.create_gl_context().realize(),t.GLContext.clear_current(),W=!0}catch(e){W=!1,G=errorMessage(e),noteWarning(`on('Gl') skipped: a display exists but no GL context realizes — ${G}`)}return W},hasGl=()=>e(s(),displayEnv(),realizeGlContext),runtimeMatch=async function(e,t){if(e.includes(`Display`))return{matched:hasDisplay(),runtime:`Display`};if(e.includes(`Gl`))return{matched:await hasGl(),runtime:`Gl`};let n=await getRuntime(),r=e.find(e=>n.includes(e));return!r||typeof t==`string`&&!n.includes(t)?{matched:!1}:{matched:!0,runtime:r,version:t}},on=async function(e,t,n){typeof e==`string`&&(e=[e]),typeof t==`function`&&(n=t,t=void 0);let{matched:r,runtime:i}=await runtimeMatch(e,t);if(!r){++h;for(let t of e)++axisRecord(t).ignored;return}z(`\nOn ${e.join(`, `)}${t?` `+t:``}`);let a=d;await n();let o=axisRecord(i??e[0]);++o.matched,o.tests+=d-a},K=[{before:[],after:[]}],currentHookFrame=()=>K[K.length-1],beforeEach=function(e){typeof e==`function`&&currentHookFrame().before.push(e)},afterEach=function(e){typeof e==`function`&&currentHookFrame().after.push(e)},runBeforeEachHooks=async()=>{for(let e of K)for(let t of e.before)await t()},runAfterEachHooks=async()=>{for(let e=K.length-1;e>=0;--e){let t=K[e];for(let e=t.after.length-1;e>=0;--e)await t.after[e]()}},it=async function(e,t,n){let r=j.get(e);if(r!==void 0){++h,z(`  ${I}-${R} ${L}${e} (skipped: ${r})${R}`);return}let i=typeof n==`number`?n:n?.timeout??k.testTimeout,a=now();++d,++y,D=e;let o=new Set;C.push(o);let s,c=!1;try{await runBeforeEachHooks(),A.noteInFlight(E?`${E} › ${e}`:e,i),await withTimeout(t,i,e)}catch(e){c=!0,s=e,e instanceof Error&&o.delete(e)}finally{try{await runAfterEachHooks()}catch(t){c?noteWarning(`afterEach also threw while "${e}" was already failing: ${errorMessage(t)}`):(c=!0,s=t,t instanceof Error&&o.delete(t))}--y,C.pop(),noteIfCwdDestroyed(e),A.noteSettled()}let l=now()-a,u=s instanceof TimeoutError?[...o]:[];if(!c){z(`  ${F}✔${R} ${L}${e}  (${formatDuration(l)})${R}`);return}++p;let m=[];c&&m.push(s?.message??String(s));for(let e of u)m.push(`${e.message}\n      ${L}↳ thrown from a callback OUTSIDE this test's awaited chain, so it could not reach the test boundary. Reject the promise from that callback (or await a helper that does) to surface it directly.${R}`);let g=m.join(`
+`),_=u[0]??s,v=c&&s instanceof TimeoutError&&u.length===0?`⏱`:`❌`;O.push({suite:E,test:e,message:g}),z(`  ${P}${v}${R} ${L}${e}  (${formatDuration(l)})${R}`),z(`${P}${g}${R}`),_?.stack&&z(_.stack)};it.skip=async function(e,t){++h,z(`  ${I}-${R} ${L}${e} (skipped)${R}`)};const getTestCounters=()=>({assertions:u,tests:d,failed:p,failedOutsideTests:m,ignored:h,xfail:_,warnings:x.length}),getAxisLedger=()=>{let e={};for(let[t,n]of v)e[t]={...n};return e};it.failing=async function(e,t,n,r){let i=typeof r==`number`?r:r?.timeout??k.testTimeout;if(typeof r==`object`&&r?.when===!1)return it(e,t,{timeout:i});let a=now();++d,++y,C.push(new Set);let o=!1;try{await runBeforeEachHooks(),await withTimeout(t,i,e)}catch{o=!0}finally{try{await runAfterEachHooks()}catch(t){noteWarning(`afterEach threw after the expected failure "${e}": ${errorMessage(t)}`)}--y,C.pop()}let s=now()-a;if(o){++_,z(`  ${I}✗${R} ${L}${e}  (expected failure — ${n})${R}`);return}++p,O.push({suite:E,test:e,message:`it.failing("${e}") PASSED — the expected failure no longer happens, so this marker is stale and must be removed (turn it back into a plain it()). It was marked expected-failing because: ${n}`}),z(`  ${P}❌${R} ${L}${e}  (${formatDuration(s)})${R}`),z(`${P}it.failing passed unexpectedly — remove the marker. Reason it carried: ${n}${R}`)};const expect=function(e,t){return++u,new U(e,!0)},failAssertion=e=>{throw e.__testFailureCounted=!0,y===0?noteStrayFailure(e?.message??String(e)):noteThrownAssertion(e),e},assert=function(e,t){++u;try{i(e,t)}catch(e){failAssertion(e)}};assert.strictEqual=function(e,t,n){++u;try{i.strictEqual(e,t,n)}catch(e){failAssertion(e)}},assert.throws=function(e,...t){++u;let n;try{e()}catch(e){n=e}try{i.throws(()=>{if(n)throw n},t[0],t[1])}catch(e){failAssertion(e)}},assert.deepStrictEqual=function(e,t,n){++u;try{i.deepStrictEqual(e,t,n)}catch(e){failAssertion(e)}};const runTests=async function(e){for(let t in e){let n=e[t];typeof n==`function`?await n():typeof n==`object`&&await runTests(n)}},browserSignalDone=()=>{let e=runtimeGlobals(),t=e.document;t&&(e.__gjsify_test_results={passed:d-p,failed:p+m,total:d,assertions:u,errors:O},t.documentElement.dataset.testsDone=`true`)},failUnexercisedAxes=async e=>{for(let t of e){let{matched:e}=await runtimeMatch([t]);if(!e)continue;let n=v.get(t);if(n&&n.tests>0)continue;++m;let r=`declared axis '${t}' ran on this host but exercised nothing — ${n?`${n.matched} gate(s) matched but executed no test, ${n.ignored} stood down`:`no on() gate named it`}`;O.push({suite:`<axis declaration>`,test:t,message:r}),z(`\n${P}❌ ${r}${R}`)}},failUnmetExpectedAxes=async()=>{let e=(envVar(`GJSIFY_TEST_EXPECT_AXES`)??``).split(`,`).map(e=>e.trim()).filter(Boolean);for(let t of e){if(!v.has(t))continue;let{matched:e}=await runtimeMatch([t]);if(e)continue;++m;let n=`axis '${t}' is expected on this host (GJSIFY_TEST_EXPECT_AXES) but stood down${t===`Gl`&&G?` — ${G}`:``}`;O.push({suite:`<axis expectation>`,test:t,message:n}),z(`\n${P}❌ ${n}${R}`)}},formatFailureVerdict=e=>{let t=[];if(e.failed&&t.push(`${e.failed} of ${e.tests} tests failed`),e.outside){let n=e.outside===1?``:`s`;t.push(e.failed?`${e.outside} failure${n} outside any test`:`${e.outside} failure${n} outside any test, ${e.tests} tests passed`)}return t.join(`, and `)},exitCodeFor=(e,t)=>e>0||t?1:0,flushed=e=>Promise.all(e.map(e=>new Promise(t=>e.write(``,()=>t())))).then(()=>void 0),printResult=()=>{let e=T>0?now()-T:0,t=e>0?`  ${L}(${formatDuration(e)})`:``,n=w?`[${w}] `:``;if(h&&z(`\n${I}✔ ${h} ignored test${h>1?`s`:``}${R}`),v.size){z(`\n${I}⊞ axes exercised${R}`);for(let[e,t]of v)z(`  ${I}↳ ${e}: ${t.tests} test${t.tests===1?``:`s`} from ${t.matched} gate${t.matched===1?``:`s`}${t.ignored?`, ${t.ignored} stood down`:``}${R}`)}if(_&&z(`\n${I}✗ ${_} expected failure${_>1?`s`:``} (it.failing — upstream defects)${R}`),x.length){z(`\n${I}⚠ ${x.length} warning${x.length>1?`s`:``} (not counted — nothing is claimed about these)${R}`);for(let e of x)z(`  ${I}↳ ${e.message.trim().split(`
 `)[0]}${R}`)}if(b.length){z(`\n${P}⚠ ${b.length} assertion${b.length>1?`s`:``} fired outside any it() (leaked from a settled test)${R}`);for(let e of b)z(`  ${P}↳ ${e.message.trim().split(`
 `)[0]}${R}`)}if(p||m){printFailureRecap(n);let e=formatFailureVerdict({failed:p,outside:m,tests:d});z(`\n${P}❌ ${n}${e}${countsSuffix()}${t}${R}`)}else z(g?`\n${P}❌ ${n}${d} test${d===1?``:`s`} passed, then a suite body threw — the run is INCOMPLETE${countsSuffix()}${t}${R}`:`\n${F}✔ ${n}${d} test${d===1?``:`s`} passed${countsSuffix()}${t}${R}`)},countsSuffix=()=>{let e=[`${u} assertion${u===1?``:`s`}`];return h&&e.push(`${h} ignored`),`  ${L}· ${e.join(` · `)}${R}`},printFailureRecap=e=>{for(let t of formatFailureRecap(O,p+m,e))z(t);if(envVar(`GITHUB_ACTIONS`))for(let t of formatFailureAnnotations(O,e))z(t)},formatFailureAnnotations=(e,t=``,n=10)=>{let escape=e=>e.replace(/%/g,`%25`).replace(/\r/g,`%0D`).replace(/\n/g,`%0A`),r=e.slice(0,n).map(e=>`::error title=${escape(`${t}${e.suite} › ${e.test}`)}::${escape(e.message.trim().split(`
 `)[0])}`);return e.length>n&&r.push(`::error title=${escape(`${t}more failures`)}::${e.length-n} further failure(s) — see the ✖ recap in the log`),r},formatFailureRecap=(e,t,n=``)=>{let r=[`\n${P}✖ ${n}failed test${e.length===1?``:`s`}${R}`];for(let t of e){let e=t.message.trim().split(`
-`)[0];r.push(`  ${P}✖ ${t.suite} › ${t.test}${R}${L} — ${e}${R}`)}return e.length!==t&&r.push(`  ${P}✖ ${t} failure${t===1?``:`s`} counted but ${e.length} named — a failure path is raising the tally without recording itself, so this list is INCOMPLETE${R}`),r},G={GJS:`Gjs`,"Node.js":`Node.js`,Bun:`Bun`,Deno:`Deno`},getRuntime=async()=>{if(w&&w!==`Unknown`)return w;let e=G[a];return e?(w=o?`${e} ${o}`:e,w):runtimeGlobals().document===void 0?w||`Unknown`:(w=`Browser`,w)},printRuntime=async()=>{let e=await getRuntime();z(`\nRunning on ${e}`)},run=async(e,t)=>{applyEnvOverrides(),installUncaughtHooks(),T=now(),j=new Map,_=0,x.length=0,v.clear(),S=probeCwd(),g=!1;let r=[];if(t&&(typeof t==`number`?k.runTimeout=t:(t.timeout!==void 0&&(k.runTimeout=t.timeout),t.testTimeout!==void 0&&(k.testTimeout=t.testTimeout),t.suiteTimeout!==void 0&&(k.suiteTimeout=t.suiteTimeout),t.skip&&(j=new Map(Object.entries(t.skip))),t.requireAxes&&(r=t.requireAxes))),A=n(envBag(),k.runTimeout),printRuntime().then(async()=>{try{await withTimeout(()=>runTests(e),k.runTimeout,`entire test run`)}catch(e){if(e instanceof TimeoutError)z(`\n${P}⏱ ${e.message}${R}`),++m,O.push({suite:`<test run>`,test:`<run timed out>`,message:e.message});else throw e}}).then(()=>failUnexercisedAxes(r)).catch(e=>{g=!0;let t=e instanceof Error?e.stack??e.message:String(e);z(`\n${P}❌ a suite body threw, so the run is INCOMPLETE and every later suite was skipped${E?` (in "${E}")`:``} — ${t}${R}`)}).then(async()=>{if(printResult(),browserSignalDone(),z(),A.stop(),c(),l?.quit(),!l){let e=exitCodeFor(p+m,g);try{(globalThis.process||await import(`node:process`)).exit(e)}catch{}}}),l?.run(),l){let e=exitCodeFor(p+m,g);runtimeGlobals().imports?.system?.exit(e)}};var K={run,assert,expect,it,afterEach,beforeEach,on,describe,configure,print:z,vi:H};export{afterEach,assert,beforeEach,configure,K as default,describe,exitCodeFor,expect,formatFailureAnnotations,formatFailureRecap,formatFailureVerdict,formatValue,getAxisLedger,getTestCounters,it,on,z as print,run,r as spy,H as vi};
+`)[0];r.push(`  ${P}✖ ${t.suite} › ${t.test}${R}${L} — ${e}${R}`)}return e.length!==t&&r.push(`  ${P}✖ ${t} failure${t===1?``:`s`} counted but ${e.length} named — a failure path is raising the tally without recording itself, so this list is INCOMPLETE${R}`),r},q={GJS:`Gjs`,"Node.js":`Node.js`,Bun:`Bun`,Deno:`Deno`},getRuntime=async()=>{if(w&&w!==`Unknown`)return w;let e=q[a];return e?(w=o?`${e} ${o}`:e,w):runtimeGlobals().document===void 0?w||`Unknown`:(w=`Browser`,w)},printRuntime=async()=>{let e=await getRuntime();z(`\nRunning on ${e}`)},run=async(e,t)=>{applyEnvOverrides(),installUncaughtHooks(),T=now(),j=new Map,_=0,x.length=0,v.clear(),S=probeCwd(),g=!1;let r=[];if(t&&(typeof t==`number`?k.runTimeout=t:(t.timeout!==void 0&&(k.runTimeout=t.timeout),t.testTimeout!==void 0&&(k.testTimeout=t.testTimeout),t.suiteTimeout!==void 0&&(k.suiteTimeout=t.suiteTimeout),t.skip&&(j=new Map(Object.entries(t.skip))),t.requireAxes&&(r=t.requireAxes))),A=n(envBag(),k.runTimeout),printRuntime().then(async()=>{try{await withTimeout(()=>runTests(e),k.runTimeout,`entire test run`)}catch(e){if(e instanceof TimeoutError)z(`\n${P}⏱ ${e.message}${R}`),++m,O.push({suite:`<test run>`,test:`<run timed out>`,message:e.message});else throw e}}).then(()=>failUnexercisedAxes(r)).then(()=>failUnmetExpectedAxes()).catch(e=>{g=!0;let t=e instanceof Error?e.stack??e.message:String(e);z(`\n${P}❌ a suite body threw, so the run is INCOMPLETE and every later suite was skipped${E?` (in "${E}")`:``} — ${t}${R}`)}).then(async()=>{if(printResult(),browserSignalDone(),z(),A.stop(),c(),l?.quit(),!l){let e=exitCodeFor(p+m,g);try{let t=globalThis.process||await import(`node:process`);await flushed([t.stdout,t.stderr]),t.exit(e)}catch{}}}),l?.run(),l){let e=exitCodeFor(p+m,g);runtimeGlobals().imports?.system?.exit(e)}};var J={run,assert,expect,it,afterEach,beforeEach,on,describe,configure,print:z,vi:H};export{afterEach,assert,beforeEach,configure,J as default,describe,exitCodeFor,expect,flushed,formatFailureAnnotations,formatFailureRecap,formatFailureVerdict,formatValue,getAxisLedger,getTestCounters,it,on,z as print,run,r as spy,H as vi};

package/lib/types/capabilities.d.ts

@@ -25,22 +25,22 @@ export declare function canRealizeSurface(os: TargetOs | undefined, env: Display
 /**
  * Can this host realize a GL context our WebGL implementation can serve?
  *
- * STRICTLY narrower than {@link canRealizeSurface}, and the reason the two carry
- * different names. macOS has a window server without `DISPLAY`, so it passes the
- * surface gate — but no CI leg has ever realized a GL context there: every darwin
- * GL measurement in `status/open-todos.md` was taken by hand on the test VM, with
- * `DYLD_LIBRARY_PATH` exported by the operator, because the `Gtk-4.0` typelib's
- * bare `libgtk-4.1.dylib` leaf does not otherwise resolve on that host (#973). So
- * the darwin answer is unknown, not no. Answering the GL question with the surface
- * answer turns macOS red for a reason the WebGL suite does not own; answering the
- * surface question with the GL answer is what kept darwin silent. win32 is excluded
- * for the measured reason in #1097: the bundled GTK resolves epoxy with no GL
- * implementation behind it.
+ * ASKED, not inferred: `probe` realizes a context and reports whether that
+ * worked, and this rule only decides whether asking is sensible at all.
  *
- * The GL 4.1 ceiling is NOT a reason to exclude darwin any more — `shaderSource()`
- * rewrites `#version 300 es` for a desktop context without ARB_ES3_compatibility,
- * and WebGL2 content draws there (measured, macOS 15.7.9 / GL 4.1 core).
+ * It used to be answered from the OS alone — Linux with a display, nothing
+ * else — because darwin was UNKNOWN rather than no (every darwin GL measurement
+ * had been taken by hand, with a loader variable the operator exported, #973),
+ * and win32's bundled GTK resolves epoxy with no GL implementation behind it on
+ * a VM without an ICD (#1097). Both reasons describe a HOST, not an OS: the
+ * first Apple Silicon Mac realized a GL 4.1 core context through GTK 4.24 and
+ * the WebGL suites ran green there, while the OS rule had kept every one of
+ * them silently skipped. An OS rule is wrong in both directions at once — it
+ * skips a Mac that has GL and would run a Linux runner whose driver has none —
+ * and the probe is the question itself, so it is right on hosts no rule named.
  *
- * Widen this the day a leg proves the context — not the day it seems plausible.
+ * Still STRICTLY narrower than {@link canRealizeSurface}: no surface, no GL, and
+ * the probe is never run where there is no display to open (a headless Linux
+ * container, where GTK's own init would fail first).
  */
-export declare function canRealizeGl(os: TargetOs | undefined, env: DisplayEnv): boolean;
+export declare function canRealizeGl(os: TargetOs | undefined, env: DisplayEnv, probe: () => boolean | Promise<boolean>): Promise<boolean>;

package/lib/types/index.d.ts

@@ -4,17 +4,13 @@ import nodeAssert from 'node:assert';
 /**
  * What each `on()` gate actually DID, per axis it named.
  *
- * `on()` answers "is this host on that axis" and returns silently when it is not,
- * which is correct — `on('Deno', …)` is supposed to contribute nothing under Node.
- * The gap is that a gate which SHOULD have fired and did not is indistinguishable
- * from one that correctly stood down: a miss only does `++countTestsIgnored`, the
- * count is printed, and neither failure counter moves. So an axis that stopped
- * running leaves nothing behind — strictly worse than a deleted test
- * file, which at least shows up as a file that is gone.
+ * `on()` answers "is this host on that axis" and returns silently when it is not, which is correct.
+ * The gap is that a gate which SHOULD have fired and did not is indistinguishable from one that
+ * correctly stood down: a miss only does `++countTestsIgnored`, and neither failure counter moves —
+ * strictly worse than a deleted test file, which at least shows up as gone.
  *
- * `tests` is the delta the matched blocks actually executed, not the number of
- * `it()` calls they contain: a block that matched and then registered nothing is
- * the exact silent shape being measured, and it must not look like coverage.
+ * `tests` is the delta the matched blocks actually executed, not the number of `it()` calls they
+ * contain: a block that matched and then registered nothing must not look like coverage.
  */
 export interface AxisRecord {
     /** Gated blocks that matched this host and ran. */
@@ -40,10 +36,10 @@ export type Callback = () => void | Promise<void>;
 /**
  * What `on()` gates on: a runtime IDENTITY, or a host CAPABILITY.
  *
- * `'Display'` and `'Gl'` are capabilities and deliberately separate — a gate must
- * state the thing it actually requires. They were one name until the WebGL suites
- * (which need a realizable GL context) and any plain GTK-surface test shared
- * `'Display'`, which made each wrong on a different OS. See `hasDisplay`/`hasGl`.
+ * `'Display'` and `'Gl'` are capabilities and deliberately separate — a gate must state the thing
+ * it actually requires. Sharing one name made each wrong on a different OS: the WebGL suites (a
+ * realizable GL context) and any plain GTK-surface test both wanted `'Display'`.
+ * See `hasDisplay`/`hasGl`.
  */
 export type Runtime = 'Gjs' | 'Deno' | 'Bun' | 'Node.js' | 'Unknown' | 'Browser' | 'Display' | 'Gl';
 export interface RunOptions {
@@ -56,21 +52,18 @@ export interface RunOptions {
     /** `expectation` → reason; skips that test and prints the reason. */
     skip?: Record<string, string>;
     /**
-     * Axes this entry claims to exercise — checked, not decorative.
-     *
-     * Each named axis that THIS host matches must have executed at least one test
-     * through an `on()` gate, or the run fails. An axis the host does not match is
-     * skipped, so one built entry can declare every axis it serves and each leg is
-     * held only to its own (see `failUnexercisedAxes`).
+     * Axes this entry claims to exercise — checked, not decorative. Each named axis that THIS
+     * host matches must have executed at least one test through an `on()` gate, or the run fails.
+     * An axis the host does not match is skipped, so one built entry can declare every axis it
+     * serves and each leg is held only to its own (see `failUnexercisedAxes`).
      */
     requireAxes?: readonly Runtime[];
 }
 export declare const print: (...data: any[]) => void;
 /**
- * Render any value for an assertion failure message WITHOUT throwing.
- * Template-literal / `+` interpolation throws a TypeError on `symbol` and `bigint`
- * operands, which would mask the real assertion result, so matchers route operands
- * through this rather than interpolating them.
+ * Render any value for an assertion failure message WITHOUT throwing. Template-literal / `+`
+ * interpolation throws a TypeError on `symbol` and `bigint` operands, which would mask the real
+ * assertion result, so matchers route operands through this rather than interpolating them.
  */
 export declare function formatValue(value: unknown): string;
 type AnyFn = (...args: any[]) => any;
@@ -175,9 +168,9 @@ export declare const getTestCounters: () => {
 /**
  * Snapshot of what each `on()` gate did, keyed by the axis it named.
  *
- * The read side of `RunOptions.requireAxes` — a copy, so a caller cannot mutate the
- * runner's tally. Same seam and same reason as `getTestCounters()`: assert against
- * the numbers the verdict is computed from, not against printed text.
+ * The read side of `RunOptions.requireAxes` — a copy, so a caller cannot mutate the runner's tally.
+ * Same seam and same reason as `getTestCounters()`: assert against the numbers the verdict is
+ * computed from, not against printed text.
  */
 export declare const getAxisLedger: () => Record<string, AxisRecord>;
 export declare const expect: (actualValue: unknown, _message?: string) => MatcherFactory;
@@ -187,46 +180,61 @@ export declare const assert: {
     throws(promiseFn: () => unknown, args_0?: nodeAssert.AssertPredicate, args_1?: string): void;
     deepStrictEqual<T>(actual: unknown, expected: T, message?: string | Error): asserts actual is T;
 };
-/**
- * The process exit code, as a pure function of the two things that decide it.
- *
- * Extracted for the same reason `formatFailureRecap` is: the two exit sites read
- * module state and call `process.exit`, neither of which a spec can reach — and this
- * rule is exactly where the regression lived. `bodyThrew` with a zero tally used to
- * answer 0, so a run that dropped eight of nine suites reported success.
- */
 /**
  * The red summary's sentence: what failed, in terms that can be true together.
  *
- * TWO CLAUSES, because they are two different facts and one ratio cannot carry
- * both. `N of M tests failed` is only true of failures a TEST owns; a stray
- * assertion, a suite timeout and an unexercised axis raise the numerator without
- * raising the denominator, and the arithmetic then says something impossible —
- * measured before the split: `3 of 2 tests failed`, and with no real tests at
- * all, `2 of 0`. A line whose whole job is to be quoted cannot print that.
+ * TWO CLAUSES, because they are two different facts and one ratio cannot carry both. `N of M tests
+ * failed` is only true of failures a TEST owns; a stray assertion, a suite timeout and an
+ * unexercised axis raise the numerator without raising the denominator, and the arithmetic then
+ * says something impossible — measured before the split: `3 of 2 tests failed`, and with no real
+ * tests at all, `2 of 0`. A line whose whole job is to be quoted cannot print that.
  *
- * Exported and pure for `failure-recap.spec.ts`'s reason: the wording is free to
- * change, the accounting is not, and a spec asserting on printed colour would
- * pin the wrong half.
+ * Exported and pure for `failure-recap.spec.ts`'s reason: the wording is free to change, the
+ * accounting is not, and a spec asserting on printed colour would pin the wrong half.
  */
 export declare const formatFailureVerdict: (counts: {
     failed: number;
     outside: number;
     tests: number;
 }) => string;
+/**
+ * The process exit code, as a pure function of the two things that decide it.
+ *
+ * Extracted for the same reason `formatFailureRecap` is: the two exit sites read module state and
+ * call `process.exit`, neither of which a spec can reach — and this rule is exactly where the
+ * regression lived. `bodyThrew` with a zero tally answered 0, so a run that dropped eight of nine
+ * suites reported success.
+ */
 export declare const exitCodeFor: (failed: number, bodyThrew: boolean) => number;
+/** The one member of a Node `Writable` that `flushed` needs. */
+export interface FlushableStream {
+    write(chunk: string, callback: (error?: Error | null) => void): unknown;
+}
+/**
+ * Resolve once everything already written to each stream has reached the OS.
+ *
+ * `process.exit()` DISCARDS output still queued in a stream, and on macOS a stdout PIPE is
+ * asynchronous in Node (synchronous on Linux, and a file is synchronous everywhere). Every CI log
+ * is a pipe. Measured on #1999: the react-native suite exited 1 on macOS with the log cut off
+ * after a passing case — the recap that named the failure was in the queue `process.exit` threw
+ * away, so the report said "exited with code 1" and nothing else. A slow reader reproduces it
+ * locally on every run; a file redirect never does, which is why it read as a crash.
+ *
+ * An empty write completes after every write queued before it. Its error argument is ignored: a
+ * reader that went away cannot be flushed to, and the exit must still happen.
+ */
+export declare const flushed: (streams: readonly FlushableStream[]) => Promise<void>;
 /**
  * The failures as GitHub Actions `::error::` workflow commands.
  *
- * Separate from the human recap because the constraints differ: a command must start
- * at column 0, carry no SGR codes (they would be printed literally in the annotation),
- * and encode newlines as `%0A`. Emitting a coloured recap line here would put escape
- * sequences on the summary page.
+ * Separate from the human recap because the constraints differ: a command must start at column 0,
+ * carry no SGR codes (they would be printed literally in the annotation), and encode newlines as
+ * `%0A`. Emitting a coloured recap line here would put escape sequences on the summary page.
  *
- * Capped, because Actions renders at most ten annotations per step and this runner is
- * launched once per runtime per shard — a 200-failure leg would spend the whole budget
- * on one shard and push every other leg's first failure off the page. The count is
- * stated when it truncates, so the cap can never read as "that was all of them".
+ * Capped, because Actions renders at most ten annotations per step and this runner is launched once
+ * per runtime per shard — a 200-failure leg would spend the whole budget on one shard and push
+ * every other leg's first failure off the page. The count is stated when it truncates, so the cap
+ * can never read as "that was all of them".
  */
 export declare const formatFailureAnnotations: (entries: ReadonlyArray<{
     suite: string;
@@ -236,11 +244,10 @@ export declare const formatFailureAnnotations: (entries: ReadonlyArray<{
 /**
  * The recap's LINES, as a pure function of the ledger and the tally.
  *
- * Split out so a spec can drive the shipping formatter: `printFailureRecap` reads
- * module-level state and writes to stdout, neither of which a test can reach — and a
- * reporter nothing tests is how the gap in #1159 lasted this long. The colour codes
- * are applied here too, so assertions see the shipped strings rather than a parallel
- * spelling of them.
+ * Split out so a spec can drive the shipping formatter: `printFailureRecap` reads module-level
+ * state and writes to stdout, neither of which a test can reach — and a reporter nothing tests is
+ * how the gap in #1159 lasted this long. The colour codes are applied here too, so assertions see
+ * the shipped strings rather than a parallel spelling of them.
  */
 export declare const formatFailureRecap: (entries: ReadonlyArray<{
     suite: string;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/unit",
-    "version": "0.52.0",
+    "version": "0.54.0",
     "description": "A BDD-style testing framework for Gjs",
     "module": "lib/esm/index.js",
     "types": "lib/types/index.d.ts",
@@ -50,22 +50,22 @@
     "devDependencies": {
         "@girs/gjs": "5.4.0",
         "@girs/glib-2.0": "5.4.0",
-        "@gjsify/cli": "^0.52.0",
+        "@gjsify/cli": "^0.54.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },
     "dependencies": {
-        "@gjsify/abort-controller": "^0.52.0",
-        "@gjsify/assert": "^0.52.0",
-        "@gjsify/buffer": "^0.52.0",
-        "@gjsify/dom-elements": "^0.52.0",
-        "@gjsify/dom-exception": "^0.52.0",
-        "@gjsify/node-globals": "^0.52.0",
-        "@gjsify/process": "^0.52.0",
-        "@gjsify/runtime": "^0.52.0",
-        "@gjsify/utils": "^0.52.0",
-        "@gjsify/web-globals": "^0.52.0",
-        "@gjsify/web-streams": "^0.52.0"
+        "@gjsify/abort-controller": "^0.54.0",
+        "@gjsify/assert": "^0.54.0",
+        "@gjsify/buffer": "^0.54.0",
+        "@gjsify/dom-elements": "^0.54.0",
+        "@gjsify/dom-exception": "^0.54.0",
+        "@gjsify/node-globals": "^0.54.0",
+        "@gjsify/process": "^0.54.0",
+        "@gjsify/runtime": "^0.54.0",
+        "@gjsify/utils": "^0.54.0",
+        "@gjsify/web-globals": "^0.54.0",
+        "@gjsify/web-streams": "^0.54.0"
     },
     "gjsify": {
         "tier": 1,