test(Obscura): runner-level acceptance suite

test/acceptance/codecept.Obscura.js mirrors codecept.Playwright.js's shape:
TestHelper.siteUrl(), Obscura in self-launch mode (no endpoint -- binary
resolved via OBSCURA_PATH/PATH, same as the existing helper-suite config),
ScreenshotSessionHelper, @codeceptjs/expect-helper, the same bootstrap/
mocha/plugins/gherkin blocks, grep: '@obscura'.

Every scenario tagged @obscura was verified empirically against the real
runner (./bin/codecept.js run -c test/acceptance/codecept.Obscura.js --grep
@obscura, both plain and --debug, run repeatedly for consistency), never
guessed. Tagged: the 4 gherkin features already carrying another engine's
tag (background/basic/before_hook/examples -- all pass), config_test.js's 6
dynamic-config scenarios + simple page test (the mock-server-dependent "make
API call" scenario fails identically for Playwright in this environment --
pre-existing, unrelated), and within_test.js's one scenario that expects an
ElementNotFound throw (genuinely correct for Obscura).

Left untagged, with root causes found rather than assumed:
- els.js's element()/eachElement()/expectElement() family requires ANY
  helper with a _locate method returning real element handles
  (lib/els.js:147); CDPBrowser has no such method and doesn't hold element
  handles at all by design (candidates are re-resolved in-page per call).
  grabWebElements/CDPElementHandle exist but don't implement the handle
  interface (.getAttribute/.click/.type/.$/.$$/etc.) els.js's consumers
  need -- building that out is a real feature, not a small fix, so this
  contradicts the mandate's "els/grabWebElements expected to work" premise
  and is reported as such rather than forced.
- within_test.js's other 10 scenarios: 9 need switchTo/iframe support
  CDPBrowser doesn't implement (I.switchTo is not a function -- confirmed
  hard incompatibility, matches expectation). The remaining one
  (locate().at().find() scoped inside within(...)) surfaced two distinct,
  pre-existing framework-level issues, not Obscura-specific, isolated via
  a minimal standalone repro: (a) lib/effects.js's within() calls
  _withinBegin via recorder.add() before invoking the within callback --
  if _withinBegin itself rejects, the callback's .then/.catch (which is
  what tears down recorder.session.start('within')) never runs, corrupting
  the recorder session for every later scenario in the same process; (b)
  the XPath a chained locate().at(N) produces is absolute ("//...", not
  ".//...") so document.evaluate(xpath, root, ...) ignores the within
  scope's root entirely -- a locator-generation issue in core, not this
  helper. Both live in lib/ and are shared across all helpers; per this
  mandate's own scope (prefer not touching lib/, fix only small/safe
  things), neither was fixed here, only diagnosed and reported.
- session_test.js: CDPBrowser has no _session (confirmed absent, matching
  the mandate's own expectation) -- session() throws "Configured helpers do
  not support starting sessions." But several of its non-async scenarios
  call session() without awaiting the (async) global wrapper, so the
  rejection becomes an unhandled promise rejection AFTER the scenario has
  already moved on, making them show as a false-positive pass with the
  session's own inner steps silently skipped. Left entirely untagged
  regardless of the runner's raw pass/fail, since none of them are
  semantically valid for a _session-less helper.
- retryTo_test.js, coverage_test.js, shadow_dom.feature: none carry a tag
  for any currently-active engine (no @Playwright/@Puppeteer/@webdriverio
  anywhere in them) -- not part of the established cross-engine comparison
  this mandate extends, so left alone rather than newly exercised only for
  Obscura.

.github/workflows/obscura.yml gets a new step after the existing unit-test
step, running the acceptance config with the same OBSCURA_PATH env
(self-launch proves itself again at runner level, as it already does for
the unit suite).

No lib/ changes. Full @obscura suite: 14 scenarios, 0 failures, run
repeatedly (plain and --debug) for consistency, no hang, clean exit.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: DavertMik

.github/workflows/obscura.yml

@@ -66,3 +66,7 @@ jobs:
         run: |
           export OBSCURA_PATH="$HOME/obscura-bin/obscura"
           npm run test:unit:webbapi:obscura
+      - name: run obscura acceptance tests
+        run: |
+          export OBSCURA_PATH="$HOME/obscura-bin/obscura"
+          ./bin/codecept.js run -c test/acceptance/codecept.Obscura.js --grep @Obscura --debug

test/acceptance/codecept.Obscura.js

@@ -0,0 +1,32 @@
+import TestHelper from '../support/TestHelper.js'
+import installCodeceptjs from '../support/install-codeceptjs.js'
+
+export const config = {
+  tests: './*_test.js',
+  timeout: 10,
+  output: './output',
+  grep: '@Obscura',
+  helpers: {
+    Obscura: {
+      url: TestHelper.siteUrl(),
+    },
+    ScreenshotSessionHelper: {
+      require: '../support/ScreenshotSessionHelper.js',
+      outputPath: 'test/acceptance/output',
+    },
+    '@codeceptjs/expect-helper': {},
+  },
+  include: {},
+  bootstrap: installCodeceptjs,
+  mocha: {},
+  plugins: {
+    retryFailedStep: {
+      enabled: true,
+    },
+  },
+  name: 'acceptance',
+  gherkin: {
+    features: './gherkin/*.feature',
+    steps: ['./gherkin/steps.js'],
+  },
+}

test/acceptance/config_test.js

@@ -1,30 +1,30 @@
 Feature('Dynamic Config').config({ url: 'https://google.com' })
 
-Scenario('change config 1 @WebDriverIO @Puppeteer @Playwright', ({ I }) => {
+Scenario('change config 1 @WebDriverIO @Puppeteer @Playwright @Obscura', ({ I }) => {
   I.amOnPage('/')
   I.dontSeeInCurrentUrl('github.com')
   I.seeInCurrentUrl('google.com')
 })
 
-Scenario('change config 2 @WebDriverIO @Puppeteer @Playwright', ({ I }) => {
+Scenario('change config 2 @WebDriverIO @Puppeteer @Playwright @Obscura', ({ I }) => {
   I.amOnPage('/')
   I.seeInCurrentUrl('codecept.io')
 }).config({ url: 'https://codecept.io' })
 
-Scenario('change config 3 @WebDriverIO @Puppeteer @Playwright', ({ I }) => {
+Scenario('change config 3 @WebDriverIO @Puppeteer @Playwright @Obscura', ({ I }) => {
   I.amOnPage('/')
   I.dontSeeInCurrentUrl('codecept.io')
   I.seeInCurrentUrl('google.com')
 })
 
-Scenario('change config 4 @WebDriverIO @Puppeteer @Playwright', ({ I }) => {
+Scenario('change config 4 @WebDriverIO @Puppeteer @Playwright @Obscura', ({ I }) => {
   I.amOnPage('/')
   I.seeInCurrentUrl('codecept.io')
 }).config(test => {
   return { url: 'https://codecept.io/', capabilities: { 'moz:title': test.title } }
 })
 
-Scenario('change config 5 @WebDriverIO @Puppeteer @Playwright', ({ I }) => {
+Scenario('change config 5 @WebDriverIO @Puppeteer @Playwright @Obscura', ({ I }) => {
   I.amOnPage('/')
   I.dontSeeInCurrentUrl('codecept.io')
   I.seeInCurrentUrl('google.com')
@@ -36,12 +36,12 @@ Scenario('make API call and check response @Playwright', ({ I }) => {
   I.seeResponseCodeIsSuccessful()
 })
 
-Scenario('change config 6 @WebDriverIO @Puppeteer @Playwright', ({ I }) => {
+Scenario('change config 6 @WebDriverIO @Puppeteer @Playwright @Obscura', ({ I }) => {
   I.amOnPage('/')
   I.seeInCurrentUrl('codecept.io')
 }).config({ url: 'https://codecept.io' })
 
-Scenario('simple page test @WebDriverIO @Puppeteer @Playwright', ({ I }) => {
+Scenario('simple page test @WebDriverIO @Puppeteer @Playwright @Obscura', ({ I }) => {
   I.amOnPage('https://example.com')
   I.see('Example Domain')
 })

test/acceptance/gherkin/background.feature

@@ -1,4 +1,4 @@
-@Puppeteer @WebDriverIO @bdd
+@Puppeteer @WebDriverIO @bdd @Obscura
 Feature: Site test
   In order to achieve my goals
   As a persona

test/acceptance/gherkin/basic.feature

@@ -1,4 +1,4 @@
-@Puppeteer @WebDriverIO @bdd
+@Puppeteer @WebDriverIO @bdd @Obscura
 Feature: Business rules
   In order to achieve my goals
   As a persona

test/acceptance/gherkin/before_hook.feature

@@ -1,4 +1,4 @@
-@Playwright @Puppeteer @WebDriverIO @bdd @hookCapture
+@Playwright @Puppeteer @WebDriverIO @bdd @hookCapture @Obscura
 Feature: Before hooks receive the real scenario
 
   Background:

test/acceptance/gherkin/examples.feature

@@ -1,4 +1,4 @@
-@Puppeteer @WebDriverIO @bdd
+@Puppeteer @WebDriverIO @bdd @Obscura
 Feature: Business examples
   In order to achieve my goals
   As a persona

test/acceptance/within_test.js

@@ -106,7 +106,7 @@ Scenario('within on nested iframe depth 2 and mixed class and xpath selector @We
   I.dontSee('Email Address')
 })
 
-Scenario('should throw exception if element not found @WebDriverIO @Puppeteer @Playwright', async ({ I }) => {
+Scenario('should throw exception if element not found @WebDriverIO @Puppeteer @Playwright @Obscura', async ({ I }) => {
   I.amOnPage('/form/textarea')
   await within('#grab-multiple', async () => {
     return await I.grabTextFrom('#first-link')