Skip to content

docs: include inherited CDPBrowser methods in Obscura/Kitesurf docs, hide abstract CDPBrowser - #5720

Merged
DavertMik merged 2 commits into
4.xfrom
docs/inherited-helper-docs
Sep 25, 2026
Merged

DavertMik merged 2 commits into
4.xfrom
docs/inherited-helper-docs

Conversation

@DavertMik

@DavertMik DavertMik commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Problem

Helper docs are generated with documentation build --shallow, one file at a time, so class inheritance isn't followed:

  • Obscura.md listed only 7 of its own methods, and Kitesurf.md only 2. None of the methods they inherit from CDPBrowser appeared.
  • Appium had a one-off docsAppium() merge with WebDriver, but it had two bugs:
    • It overwrote Appium.md after the markdown cleanup ran, leaving 27 (optional, default …) fragments on the page.
    • It read docs/build/WebDriver.js before that file was rebuilt in the same run. That's the likely reason about 45 WebDriver methods (amOnPage, attachFile, type, …) were missing from Appium's page.

Changes

  • runok.cjs and Bunoshfile.js:
    • docsAppium() is replaced by a general inheritedHelperDocs map plus docsInheritedHelper(): Appium ← WebDriver (the existing web-only excludes are kept), Obscura ← CDPBrowser, Kitesurf ← CDPBrowser.
    • Parent methods and parent config options are merged in. When both define one, the subclass version wins. Kitesurf skips endpoint and headers, because it sets them itself.
    • Every helper is prepared in docs/build/ first and markdown is generated afterwards, so a parent is never stale.
    • Merged output goes through the same cleanup as every other helper page.
  • CDPBrowser is abstract: it's on a new abstractHelpers list, so its page isn't generated, and docs/helpers/CDPBrowser.md is deleted.
  • docs/alternative-browsers.md: the direct CDPBrowser config example and the /helpers/CDPBrowser link are removed.
  • lib/helper/Obscura.js: the config JSDoc no longer points readers to the CDPBrowser config table.
  • All helper pages are now generated through the documentation JS API. The output was checked to be identical to the CLI's for a sample helper. This lets the script:
    • drop base Helper lifecycle hooks (_init, _before, _after, _beforeStep, _afterStep, _beforeSuite, _afterSuite, _passed, _failed, _finishTest, _setConfig, _validateConfig, _test, _useTo)
    • list the remaining _-prefixed methods after all public methods
  • runok.cjs now imports documentation inside the generator instead of relying on an unawaited top-level import().

Result

  • Obscura.md now has 143 method headings (up from 7) and Kitesurf.md has 138 (up from 2).
  • Both Configuration tables include the inherited CDPBrowser options.
  • Appium.md no longer has leftover (optional, default …) text, and all its reference links resolve.

Public methods on every helper page are unchanged by the reordering. The helper pages in this PR were regenerated with ./runok.cjs docs:helpers.

🤖 Generated with Claude Code

DavertMik and others added 2 commits September 23, 2026 17:05
Helper docs are built with `documentation --shallow`, so subclasses only
listed their own methods. Generalize the Appium/WebDriver merge into
`inheritedHelperDocs` and apply it to Obscura and Kitesurf (parent
CDPBrowser), including parent config properties.

Build all docs/build files before generating markdown so a parent is never
stale, and run the merged output through the same post-processing (fixes
leftover "(optional, default ...)" in Appium.md).

CDPBrowser is abstract: stop generating its page and drop links to it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Generate every helper page through the documentation API so members can
be post-processed: base Helper hooks (_before, _after, _beforeStep, ...)
are dropped, and remaining _-prefixed methods are sorted after public API.

Import `documentation` inside the generator instead of relying on an
unawaited top-level import().

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@DavertMik
DavertMik merged commit 6c45750 into 4.x Sep 25, 2026
14 checks passed
@DavertMik
DavertMik deleted the docs/inherited-helper-docs branch September 25, 2026 00:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant