@cepharum/contextual-gherkin 3.0.0 → 4.0.0

package/index.d.ts

@@ -1,17 +1,29 @@
 declare module "@cepharum/contextual-gherkin" {
-	import {Browser, BrowserContextOptions, Expect, Mouse} from "@playwright/test";
+	import {Browser, BrowserContextOptions, Expect, LaunchOptions, Locator, Mouse} from "@playwright/test";
+
+	type PlaywrightActualBrowserName = "chromium" | "firefox" | "webkit";
+
+	type PlaywrightSupportedBrowserName = PlaywrightActualBrowserName | "chrome" | "safari" | "edge";
 
 	/**
 	 * Exposes helper functions for conveniently integrating contextual-gherkin
 	 * with different frameworks for running tests.
 	 */
-	const use = {
+	namespace use {
 		/**
 		 * Generates adapter for running tests based on contextual-gherkin with
-		 * playwright as test runner. The returned promise resolves with an
-		 * adapter suitable for use with function ContextualGherkin().
-		 */
-		async playwright(): Promise<PlaywrightAdapter> {}
+		 * playwright. The returned promise resolves with an adapter suitable
+		 * for use with function ContextualGherkin().
+		 *
+		 * @param browserName name of browser to use, defaults to "chromium"
+		 * @param browserOptions options used on launching the selected browser
+		 * @param contextOptions options used on creating (another) context in selected browser
+		 */
+		function playwright(
+            browserName?: PlaywrightSupportedBrowserName,
+            browserOptions?: LaunchOptions,
+            contextOptions?: BrowserContextOptions
+        ): Promise<PlaywrightAdapter>;
 	}
 
 	/**
@@ -29,13 +41,13 @@ declare module "@cepharum/contextual-gherkin" {
 	 * @param adapter interface for interacting with a browser instance
 	 * @returns promise for instance of contextual-gherkin
 	 */
-	async function ContextualGherkin(configuration?: Configuration, adapter?: BrowserAdapter): Promise<Api>;
+	function ContextualGherkin(configuration?: Configuration, adapter?: BrowserAdapter): Promise<Api>;
 
 	/**
 	 * Implements singleton API instance for interacting with contextual-gherkin
 	 * in current runtime.
 	 */
-	class Api<B = BrowserAdapter<C, A>, C = AbstractContext, A = Assertions> {
+	class Api<C = AbstractContext, A = Assertions, B = BrowserAdapter<C, A>> {
 		/**
 		 * Creates singleton instance of contextual-gherkin API in current
 		 * runtime on first invocation or augments configuration of existing
@@ -44,13 +56,13 @@ declare module "@cepharum/contextual-gherkin" {
 		 * @param config configuration of singleton instance, gets merged with previously provided configuration
 		 * @param browser adapter for interacting with a browser, required on first invocation, rejected on succeeding invocations
 		 */
-		static async setup( config: Configuration, browser?: B ): Promise<Api<C, A, B>>;
+		static setup<C = AbstractContext, A = Assertions, B = BrowserAdapter<C, A>>( config: Configuration, browser?: B ): Promise<Api<C, A, B>>;
 
 		/**
 		 * Provides singleton instance of current runtime's contextual-gherkin
 		 * API for interacting with content of one or more browser views.
 		 */
-		static access<BA = B, AC = C, AS = A>(): Api<BA, AC, AS>;
+		static access<C = AbstractContext, A = Assertions, B = BrowserAdapter<C, A>>(): Api<C, A, B>;
 
 		/**
 		 * Exposes normalized configuration of contextual-gherkin.
@@ -85,13 +97,13 @@ declare module "@cepharum/contextual-gherkin" {
 		/**
 		 * Explicitly creates view with provided name.
 		 *
-		 * @param name name of view to create
-		 * @param sharedSession if true, created view shares its session with current one (e.g. having same user authenticated)
-		 * @param select if true, created view is implicitly selected to be current one in follow-up interactions
+		 * @param name name of view to create, "default" when omitted
+		 * @param sharedSession if true, created view shares its session with current one (e.g. having same user authenticated), defaults to true
+		 * @param select if true, created view is implicitly selected to be current one in follow-up interactions, defaults to false
 		 * @returns promise for context to interact with named view
 		 * @throws TypeError if named view has been created before
 		 */
-		async createView( name: string = "default", sharedSession: boolean = true, select: boolean = false ): Promise<C>;
+		createView( name: string, sharedSession: boolean, select: boolean ): Promise<C>;
 
 		/**
 		 * Fetches view by its name, creating it if necessary.
@@ -100,10 +112,10 @@ declare module "@cepharum/contextual-gherkin" {
 		 * current view. Use @see Api#createView() to create a view with a
 		 * dedicated session.
 		 *
-		 * @param name name of view to fetch
+		 * @param name name of view to fetch, "default" when omitted
 		 * @returns promise for context to interact with named view
 		 */
-		async getViewByName( name: string = "default" ): Promise<C>;
+		getViewByName( name?: string ): Promise<C>;
 
 		/**
 		 * Fetches view by its name, creating it if necessary, and selects it as
@@ -113,10 +125,10 @@ declare module "@cepharum/contextual-gherkin" {
 		 * current view. Use @see Api#createView() to create a view with a
 		 * dedicated session.
 		 *
-		 * @param name name of view to select
+		 * @param name name of view to select, "default" when omitted
 		 * @returns promise for context to interact with named view
 		 */
-		async selectViewByName( name: string = "default" ): Promise<C>;
+		selectViewByName( name?: string ): Promise<C>;
 
 		/**
 		 * Clears histories of all currently managed views.
@@ -168,7 +180,7 @@ declare module "@cepharum/contextual-gherkin" {
 		 *
 		 * @returns promise resolved when test runner has been resumed
 		 */
-		async debug(): Promise<void>;
+		debug(): Promise<void>;
 
 		/**
 		 * Creates promise resolved after giving number of milliseconds.
@@ -176,7 +188,7 @@ declare module "@cepharum/contextual-gherkin" {
 		 * @param ms number of milliseconds to wait before resolving returned promise
 		 * @returns promise resolved after given number of milliseconds
 		 */
-		async wait( ms: number ): Promise<void>;
+		wait( ms: number ): Promise<void>;
 
 		/**
 		 * Gets all aliases of provided type name.
@@ -242,13 +254,13 @@ declare module "@cepharum/contextual-gherkin" {
 		 * @param shareSessionWith provides reference on a previously created view's context to share session with
 		 * @returns promise created view's context
 		 */
-		async createView( api: Api<BrowserAdapter, C>, shareSessionWith?: C ): Promise<C>;
+		createView( api: Api<BrowserAdapter, C>, shareSessionWith?: C ): Promise<C>;
 
 		/**
 		 * Destructs connection to browser by means of closing the controlled
 		 * browser invalidating all its views implicitly.
 		 */
-		async disconnect(): Promise<void>;
+		disconnect(): Promise<void>;
 
 		/**
 		 * Compiles set of methods available for triggering actions on elements
@@ -256,12 +268,12 @@ declare module "@cepharum/contextual-gherkin" {
 		 *
 		 * @param locator description of elements resulting actions are performed on
 		 */
-		async getActions( locator: any ): Promise<Actions>;
+		getActions( locator: any ): Promise<Actions>;
 
 		/**
 		 * Provides assertions library for assessing state of elements.
 		 */
-		async getAssertions(): Promise<() => A>;
+		getAssertions(): Promise<() => A>;
 	}
 
 	/**
@@ -271,7 +283,7 @@ declare module "@cepharum/contextual-gherkin" {
 		constructor( browser: PlaywrightBrowser, contextOptions?: PlaywrightBrowserContextOptions );
 
 		/** @inheritDoc */
-		async createView( api: Api<PlaywrightAdapter, PlaywrightContext>, shareSessionWith: PlaywrightContext = undefined ): Promise<PlaywrightContext>;
+		createView( api: Api<PlaywrightAdapter, PlaywrightContext>, shareSessionWith?: PlaywrightContext ): Promise<PlaywrightContext>;
 	}
 
 	/**
@@ -513,7 +525,7 @@ declare module "@cepharum/contextual-gherkin" {
 		subIndex?: number;
 	}
 
-	/**
+    /**
 	 * Defines common API of a context.
 	 *
 	 * Every context is managing a set of elements in the document of a connected
@@ -523,18 +535,19 @@ declare module "@cepharum/contextual-gherkin" {
 	 * Contexts can be tracked and recovered to implement follow-up queries and
 	 * actions.
 	 */
+	// @ts-ignore
 	abstract class AbstractContext<C = AbstractContext> {
 		/**
 		 * @param framework names the framework this context is working with
 		 * @param source context this instance is starting as a duplicate of
 		 */
-		constructor( framework: ContextFramework, source?: T );
+		constructor( framework: ContextFramework, source?: C );
 
 		/**
 		 * Provides history of recently queried elements tracked per type of
 		 * element.
 		 */
-		history: ContextHistoryByElementType<T>;
+		history: ContextHistoryByElementType<C>;
 
 		/**
 		 * Names framework current context is used to interact with a connected
@@ -554,7 +567,7 @@ declare module "@cepharum/contextual-gherkin" {
 		 * It usually addresses ascendants of current context's set of matching
 		 * elements.
 		 */
-		parent?: Context;
+		parent?: C;
 
 		/**
 		 * Exposes singular form of type name used to pick a query for
@@ -662,7 +675,7 @@ declare module "@cepharum/contextual-gherkin" {
 		 * @param defaultSelector selector to use in case none has been configured for the given type
 		 * @returns another context representing all matching elements found as descendants of elements in current context
 		 */
-		find( typeOfElement: string, defaultSelector?: SimpleSelector ): Context;
+		find( typeOfElement: string, defaultSelector?: SimpleSelector ): AbstractContext;
 
 		/**
 		 * Reduces current set of matching elements to the one at given index.
@@ -674,21 +687,46 @@ declare module "@cepharum/contextual-gherkin" {
 		 * @param index non-nullish index into current context's set of matching elements to pick
 		 * @returns another context representing that selected element, only, current context if index is nullish
 		 */
-		nth( index: number|null ): Context;
+		nth( index: number|null ): AbstractContext;
 
 		/**
-		 * Reduces current context's set of matching elements to those matching
-		 * another selector for given type of element.
+		 * Limits current set of matching elements to those also matching the
+		 * selector configured for a given element type, intersecting the current
+		 * set rather than searching descendants.
 		 *
-		 * @note In opposition to filter(), this function isn't descending into
-		 *       the hierarchy of elements but inspects currently matching
-		 *       elements, only.
+		 * @param typeOfElement type of element to intersect current matches with
+		 * @param defaultSelector selector to use if none has been configured for the named type of elements
+		 * @returns another context representing only those matching elements of current context that also match selector of given type
+		 */
+		filterByType( typeOfElement: string, defaultSelector?: SimpleSelector ): AbstractContext;
+
+		/**
+		 * Limits current set of matching elements to those also matching a given
+		 * selector, intersecting the current set rather than searching descendants.
 		 *
-		 * @param typeOfElement type of element to reduce matches to
+		 * @param selector selector string to intersect current matches with
+		 * @returns another context representing only those matching elements of current context that also match given selector
+		 */
+		filterBySelector( selector: string ): AbstractContext;
+
+		/**
+		 * Limits current set of matching elements to those containing a descendant
+		 * matching the selector configured for a given element type.
+		 *
+		 * @param typeOfElement type of element to look for in descendants
 		 * @param defaultSelector selector to use if none has been configured for the named type of elements
-		 * @returns another context representing only those matching elements of current context that match selector of given name, too
+		 * @returns another context representing only those matching elements of current context that contain a descendant of given type
+		 */
+		filterBySubType( typeOfElement: string, defaultSelector?: SimpleSelector ): AbstractContext;
+
+		/**
+		 * Limits current set of matching elements to those containing a descendant
+		 * matching a given selector.
+		 *
+		 * @param selector selector string to look for in descendants
+		 * @returns another context representing only those matching elements of current context that contain a descendant matching given selector
 		 */
-		filter( typeOfElement: string, defaultSelector?: SimpleSelector ): Context;
+		filterBySubSelector( selector: string ): AbstractContext;
 
 		/**
 		 * Reduces current context's set of matching elements to those marked as
@@ -704,7 +742,7 @@ declare module "@cepharum/contextual-gherkin" {
 		 * @param closureScope set of simple values to be provided as closure scope to invoked callback
 		 * @returns another context representing only those matching elements of current context that cause provided callback to return truthy
 		 */
-		filterFn( fn: SelectorFn, closureScope?: { [key: string]: any } ): Context;
+		filterFn( fn: SelectorFn, closureScope?: { [key: string]: any } ): AbstractContext;
 
 		/**
 		 * Reduces current context's set of matching elements to those having
@@ -728,7 +766,7 @@ declare module "@cepharum/contextual-gherkin" {
 		 * @param closureScope set of simple values to be provided as closure scope to invoked callback
 		 * @returns another context representing only those matching elements of current context that have children causing provided callback to return truthy
 		 */
-		filterBySubsWithFn( typeOfSub: string, defaultSelector: SimpleSelector, fn: SelectorFn, closureScope?: { [key: string]: any } ): Context;
+		filterBySubsWithFn( typeOfSub: string, defaultSelector: SimpleSelector, fn: SelectorFn, closureScope?: { [key: string]: any } ): AbstractContext;
 
 		/**
 		 * Implements a convenient helper to filter current set of matching
@@ -741,7 +779,7 @@ declare module "@cepharum/contextual-gherkin" {
 		 * @param partially if true, given text or regular expression is expected to be a part of a child's normalized textual content, only
 		 * @returns another context limited to those matching elements of current context that have children with a given text
 		 */
-		filterBySubsWithText( typeOfSub: string, defaultSelector: SimpleSelector, text: string|RegExp, partially?: boolean ): Context;
+		filterBySubsWithText( typeOfSub: string, defaultSelector: SimpleSelector, text: string|RegExp, partially?: boolean ): AbstractContext;
 
 		/**
 		 * Limits set of matching elements to those with a named attribute
@@ -751,7 +789,7 @@ declare module "@cepharum/contextual-gherkin" {
 		 * @param value value to expect in a matching element's attribute
 		 * @returns another context with all those elements of current one which have a matching value in named attribute
 		 */
-		withAttribute( name: string, value: string|RegExp|boolean ): Context;
+		withAttribute( name: string, value: string|RegExp|boolean ): AbstractContext;
 
 		/**
 		 * Limits set of matching elements to those with a named DOM property
@@ -768,7 +806,7 @@ declare module "@cepharum/contextual-gherkin" {
 		 * @param value value to expect in a matching element's DOM property, use callback invoked with found value to return truthy on a match
 		 * @returns another context with all those elements of current one which have a matching value in named DOM property
 		 */
-		withProperty( name: string, value: string|RegExp|boolean|SelectorFn ): Context;
+		withProperty( name: string, value: string|RegExp|boolean|SelectorFn ): AbstractContext;
 
 		/**
 		 * Limits set of matching elements to those with a named DOM property
@@ -777,10 +815,10 @@ declare module "@cepharum/contextual-gherkin" {
 		 *
 		 * @param name name of DOM property to inspect, might be mapped internally according to selectors configuration
 		 * @param value value to expect in a matching element's DOM property, use callback invoked with found value to return truthy on a match
-		 * @param negated if true, value must not be included with any named property of currently matching elements
+		 * @param negated if true, value must not be included with any named property of currently matching elements, false by default
 		 * @returns another context with all those elements of current one which have a matching value in named DOM property
 		 */
-		withListProperty( name: string, value: string, negated: boolean = false ): Context;
+		withListProperty( name: string, value: string, negated?: boolean ): AbstractContext;
 
 		/**
 		 * Detaches current context from its original query used to address
@@ -792,7 +830,7 @@ declare module "@cepharum/contextual-gherkin" {
 		 *
 		 * @param cardinality cardinality of resulting context
 		 */
-		detach( cardinality?: Cardinality ): Promise<Context>;
+		detach( cardinality?: Cardinality ): Promise<AbstractContext>;
 
 		/**
 		 * Tracks detached version of current context in history of contexts for
@@ -812,7 +850,7 @@ declare module "@cepharum/contextual-gherkin" {
 		 * @param cardinality selects expected number of elements in match to find
 		 * @returns previously tracked context matching parameters
 		 */
-		getTracked( typeOfElement, index, cardinality = null ): Context;
+		getTracked( typeOfElement, index, cardinality? ): AbstractContext;
 
 		/**
 		 * Looks up runtime configuration for a selector matching provided
@@ -830,11 +868,11 @@ declare module "@cepharum/contextual-gherkin" {
 		 * provided data extracted from a {cardinal-word} expression.
 		 *
 		 * @param cardinal data of an encountered {cardinal-word} expression
-		 * @param track controls if current context should be tracked in history after passing check
-		 * @param message custom message to display if check fails
+		 * @param track controls if current context should be tracked in history after passing check, true by default
+		 * @param message custom message to display if check fails, "expecting %amount" by default
 		 * @returns promise resolved when check has passed and context has been optionally tracked
 		 */
-		checkCardinalWord(cardinal: NumberAndWord, track: boolean = true, message: string = "expecting %amount" ): Promise<void>;
+		checkCardinalWord(cardinal: NumberAndWord, track?: boolean, message?: string ): Promise<void>;
 
 		/**
 		 * Conveniently asserts that some or all matching elements of current
@@ -850,11 +888,11 @@ declare module "@cepharum/contextual-gherkin" {
 		 *
 		 * @param filteredContext another context of matching elements to compare with current one
 		 * @param contextualWord parsed instance of `{contextual-word}` used to fetch current context from history
-		 * @param requireAll if true, provided context has to list all elements of current context, otherwise it has to list at least one element
-		 * @param track if true, this context is tracked if it has been reduced after fetching it from context due to provided `phrase`
+		 * @param requireAll if true, provided context has to list all elements of current context, otherwise it has to list at least one element, true by default
+		 * @param track if true, this context is tracked if it has been reduced after fetching it from context due to provided `phrase`, true by default
 		 * @returns promise resolved when check has passed and context has been optionally tracked in history
 		 */
-		checkFilteredInContext( filteredContext: Context, contextualWord: ContextualWord, requireAll: boolean = true, track: boolean = true ): Promise<void>;
+		checkFilteredInContext( filteredContext: AbstractContext, contextualWord: ContextualWord, requireAll?: boolean, track?: boolean ): Promise<void>;
 	}
 
 	/**
@@ -908,7 +946,7 @@ declare module "@cepharum/contextual-gherkin" {
 		 *
 		 * @param target context addressing target element(s) is/are dragged to
 		 */
-		dragTo(target: context): Promise<void>;
+		dragTo(target: AbstractContext): Promise<void>;
 
 		/**
 		 * Dispatches custom event to elements matching current context.
@@ -992,7 +1030,7 @@ declare module "@cepharum/contextual-gherkin" {
 		 * Provides the locator used to query a connected browser's page for
 		 * matching elements.
 		 */
-		locator: Locator;
+		locator: PlaywrightLocator;
 	}
 
 	// re-define some playwright types with a custom name so for using it in
@@ -1003,32 +1041,32 @@ declare module "@cepharum/contextual-gherkin" {
 
 	type Action = "click" | "hover" | "enter";
 
-	async function globalFind( cardinal: NumberAndWord ): Promise<void>;
-	async function globalFindByAttribute( cardinal: NumberAndWord, name: string, value: string|RegExp ): Promise<void>;
-	async function globalFindByProperty( cardinal: NumberAndWord, name: string, value: string|RegExp ): Promise<void>;
-	async function globalFindByClass( cardinal: NumberAndWord, className: string, negated: boolean ): Promise<void>;
-	async function globalFindByLabel( cardinal: NumberAndWord, label: string, partially: boolean ): Promise<void>;
-	async function globalFindByTextContent( cardinal: NumberAndWord, text: string, partially: boolean ): Promise<void>;
-
-	async function globalActionByAttribute( cardinal: NumberAndWord, name: string, value: string|RegExp, action: Action, input?: string ): Promise<void>;
-	async function globalActionByProperty( cardinal: NumberAndWord, name: string, value: string|RegExp, action: Action, input?: string ): Promise<void>;
-	async function globalActionByClass( cardinal: NumberAndWord, className: string, negated?: boolean, action: Action, input?: string ): Promise<void>;
-	async function globalActionByLabel( cardinal: NumberAndWord, label: string, partially: boolean, action: Action, input?: string ): Promise<void>;
-	async function globalActionByTextContent( cardinal: NumberAndWord, text: string, partially: boolean, action: Action, input?: string ): Promise<void>;
-
-	async function localFind( phrase: ContextualWord, cardinal: NumberAndWord ): Promise<void>;
-	async function localFindByAttribute( phrase: ContextualWord, cardinal: NumberAndWord, name: string, value: string|RegExp ): Promise<void>;
-	async function localFindByProperty( phrase: ContextualWord, cardinal: NumberAndWord, name: string, value: string|RegExp ): Promise<void>;
-	async function localFindByClass( phrase: ContextualWord, cardinal: NumberAndWord, className: string, negated: boolean ): Promise<void>;
-	async function localFindByLabel( phrase: ContextualWord, cardinal: NumberAndWord, label: string, partially: boolean ): Promise<void>;
-	async function localFindByTextContent( phrase: ContextualWord, cardinal: NumberAndWord, text: string, partially: boolean ): Promise<void>;
-
-	async function localAction( phrase: ContextualWord, action: Action, input?: string ): Promise<void>;
-
-	async function localStateByAttribute( phrase: ContextualWord, all: boolean, name: string, value: string|RegExp ): Promise<void>;
-	async function localStateByProperty( phrase: ContextualWord, all: boolean, name: string, value: string|RegExp ): Promise<void>;
-	async function localStateByClass( phrase: ContextualWord, all: boolean, className: string, negated: boolean ): Promise<void>;
-	async function localStateByLabel( phrase: ContextualWord, label: string, partially: boolean ): Promise<void>;
-	async function localStateByTextContent( phrase: ContextualWord, text: string, partially: boolean ): Promise<void>;
-	async function localStateExists( phrase: ContextualWord, mustExist: boolean ): Promise<void>;
+	function globalFind( cardinal: NumberAndWord ): Promise<void>;
+	function globalFindByAttribute( cardinal: NumberAndWord, name: string, value: string|RegExp ): Promise<void>;
+	function globalFindByProperty( cardinal: NumberAndWord, name: string, value: string|RegExp ): Promise<void>;
+	function globalFindByClass( cardinal: NumberAndWord, className: string, negated: boolean ): Promise<void>;
+	function globalFindByLabel( cardinal: NumberAndWord, label: string, partially: boolean ): Promise<void>;
+	function globalFindByTextContent( cardinal: NumberAndWord, text: string, partially: boolean ): Promise<void>;
+
+	function globalActionByAttribute( cardinal: NumberAndWord, name: string, value: string|RegExp, action: Action, input?: string ): Promise<void>;
+	function globalActionByProperty( cardinal: NumberAndWord, name: string, value: string|RegExp, action: Action, input?: string ): Promise<void>;
+	function globalActionByClass( cardinal: NumberAndWord, className: string, negated: boolean, action: Action, input?: string ): Promise<void>;
+	function globalActionByLabel( cardinal: NumberAndWord, label: string, partially: boolean, action: Action, input?: string ): Promise<void>;
+	function globalActionByTextContent( cardinal: NumberAndWord, text: string, partially: boolean, action: Action, input?: string ): Promise<void>;
+
+	function localFind( phrase: ContextualWord, cardinal: NumberAndWord ): Promise<void>;
+	function localFindByAttribute( phrase: ContextualWord, cardinal: NumberAndWord, name: string, value: string|RegExp ): Promise<void>;
+	function localFindByProperty( phrase: ContextualWord, cardinal: NumberAndWord, name: string, value: string|RegExp ): Promise<void>;
+	function localFindByClass( phrase: ContextualWord, cardinal: NumberAndWord, className: string, negated: boolean ): Promise<void>;
+	function localFindByLabel( phrase: ContextualWord, cardinal: NumberAndWord, label: string, partially: boolean ): Promise<void>;
+	function localFindByTextContent( phrase: ContextualWord, cardinal: NumberAndWord, text: string, partially: boolean ): Promise<void>;
+
+	function localAction( phrase: ContextualWord, action: Action, input?: string ): Promise<void>;
+
+	function localStateByAttribute( phrase: ContextualWord, all: boolean, name: string, value: string|RegExp ): Promise<void>;
+	function localStateByProperty( phrase: ContextualWord, all: boolean, name: string, value: string|RegExp ): Promise<void>;
+	function localStateByClass( phrase: ContextualWord, all: boolean, className: string, negated: boolean ): Promise<void>;
+	function localStateByLabel( phrase: ContextualWord, label: string, partially: boolean ): Promise<void>;
+	function localStateByTextContent( phrase: ContextualWord, text: string, partially: boolean ): Promise<void>;
+	function localStateExists( phrase: ContextualWord, mustExist: boolean ): Promise<void>;
 }

package/lib/adapter/playwright.js

@@ -3,7 +3,7 @@ import { PlaywrightContext } from "../context/playwright.js";
 import { clientHelper } from "../support/playwright/client-helper.js";
 
 /**
- * @implements {BrowserAdapter}
+ * @extends {BrowserAdapter}
  */
 export class PlaywrightAdapter {
 	/**
@@ -33,7 +33,7 @@ export class PlaywrightAdapter {
 	}
 
 	/**
-	 * @param {cgApi} api
+	 * @param {Api} api
 	 * @param {PlaywrightContext} shareSessionWith
 	 */
 	async createView( api, shareSessionWith = undefined ) {

package/lib/api.js

@@ -84,7 +84,9 @@ export class Api {
 	 */
 	static access() {
 		if ( !singleton ) {
-			throw new Error( "missing contextual-gherkin API ... see https://cepharum-foss.gitlab.io/contextual-gherkin/api/configuration.html" );
+			throw Object.assign( new Error( "missing contextual-gherkin API ... see https://cepharum-foss.gitlab.io/contextual-gherkin/api/configuration.html" ), {
+				missingContextualGherkin: true,
+			} );
 		}
 
 		return singleton;

package/lib/cli.js

@@ -1,5 +1,4 @@
 import File from "node:fs/promises";
-import OS from "node:os";
 import Path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
@@ -13,25 +12,6 @@ export function getMyFolder() {
 	return Path.resolve( fileURLToPath( import.meta.url ), "../.." );
 }
 
-/**
- * Gathers information on named file without throwing in case the file simply
- * does not exist.
- *
- * @param {string} filename name of file to inspect
- * @returns {Promise<Stats|null>} promise for found file's information, null if file is missing
- */
-export async function statFile( filename ) {
-	try {
-		return await File.stat( filename );
-	} catch ( cause ) {
-		if ( cause.code === "ENOENT" ) {
-			return null;
-		}
-
-		throw cause;
-	}
-}
-
 /**
  * Reads single package.json file.
  */
@@ -237,40 +217,6 @@ export function parseArguments( argv ) {
 	};
 }
 
-/**
- * Inspects npm executable used to invoke cucumber-js.
- *
- * @paranm {Object<string,string>} env set of environment variables
- * @returns {Promise<Object<string,any>>} promise for options to properly spawn npm
- */
-export async function detectNpmOptions( env ) {
-	const envPath = env.PATH ?? env.Path;
-	const isWindows = OS.platform() === "win32";
-
-	for ( const path of envPath.split( Path.delimiter ) ) {
-		const candidate = Path.resolve( path, isWindows ? "npm.cmd" : "npm" );
-		const npmStat = await statFile( candidate ); // eslint-disable-line no-await-in-loop
-
-		if ( npmStat?.isFile() || npmStat?.isSymbolicLink() ) {
-			const spawnOptions = {
-				shell: candidate.endsWith( ".cmd" ),
-			};
-
-			if ( !spawnOptions.shell ) {
-				const file = await File.readFile( candidate, "utf8" ); // eslint-disable-line no-await-in-loop
-
-				if ( file.startsWith( "#!/" ) ) {
-					spawnOptions.shell = true;
-				}
-			}
-
-			return spawnOptions;
-		}
-	}
-
-	return undefined;
-}
-
 /**
  * Inspects existing dependency @cucumber/cucumber for the pathname of script
  * implementing the CLI binary of cucumber.

package/lib/context/playwright.js

@@ -171,25 +171,78 @@ export class PlaywrightContext extends AbstractContext {
 	}
 
 	/**
-	 * Limits current set of matches to those matching as a given type of
-	 * elements, too.
+	 * Limits current set of matches to those also matching a given element
+	 * type's selector, intersecting the current set rather than searching
+	 * descendants.
 	 *
-	 * @param {string} typeOfElement names type of elements to focus on
+	 * @param {string} typeOfElement names type of elements to intersect with
 	 * @param {SimpleSelector} defaultSelector selector to use as fallback
-	 * @returns {Context} node describing matches of filtering and their processing context
+	 * @returns {Context} node describing the filtered set of elements
 	 */
-	filter( typeOfElement, defaultSelector = undefined ) {
+	filterByType( typeOfElement, defaultSelector = undefined ) {
 		const type = this.api.toNormalizedSingularName( typeOfElement );
 		const { query, dependencies } = this.getSelector( type, defaultSelector );
 
 		return new this.constructor( this, {
-			locator: this.locator.filter( { has: this.createSubLocator( query, dependencies ) } ),
+			locator: this.locator.and( this.createSubLocator( query, dependencies, true ) ),
 			type: this.type,
 			selectors: this.selectors,
 			cardinality: this.cardinality
 		} );
 	}
 
+	/**
+	 * Limits current set of matches to those also matching a given selector,
+	 * intersecting the current set rather than searching descendants.
+	 *
+	 * @param {string} selector selector string accepted by Playwright locators
+	 * @returns {Context} node describing the filtered set of elements
+	 */
+	filterBySelector( selector ) {
+		return new this.constructor( this, {
+			locator: this.locator.and( this.locator.page().locator( selector ) ),
+			type: this.type,
+			selectors: this.selectors,
+			cardinality: this.cardinality,
+		} );
+	}
+
+	/**
+	 * Limits current set of matches to those containing a descendant matching
+	 * a given element type's selector.
+	 *
+	 * @param {string} typeOfElement names type of elements to look for in descendants
+	 * @param {SimpleSelector} defaultSelector selector to use as fallback
+	 * @returns {Context} node describing the filtered set of elements
+	 */
+	filterBySubType( typeOfElement, defaultSelector = undefined ) {
+		const type = this.api.toNormalizedSingularName( typeOfElement );
+		const { query, dependencies } = this.getSelector( type, defaultSelector );
+
+		return new this.constructor( this, {
+			locator: this.locator.filter( { has: this.createSubLocator( query, dependencies ) } ),
+			type: this.type,
+			selectors: this.selectors,
+			cardinality: this.cardinality,
+		} );
+	}
+
+	/**
+	 * Limits current set of matches to those containing a descendant matching
+	 * a given selector.
+	 *
+	 * @param {string} selector selector string accepted by Playwright locators
+	 * @returns {Context} node describing the filtered set of elements
+	 */
+	filterBySubSelector( selector ) {
+		return new this.constructor( this, {
+			locator: this.locator.filter( { has: this.locator.page().locator( selector ) } ),
+			type: this.type,
+			selectors: this.selectors,
+			cardinality: this.cardinality,
+		} );
+	}
+
 	/**
 	 * Limits current set of matches to those picked by a given callback
 	 * function invoked in browser.

package/lib/support/playwright/create-adapter.js

@@ -1,4 +1,4 @@
-import { firefox, chromium, webkit } from "playwright";
+import { firefox, chromium, webkit } from "@playwright/test";
 
 import { PlaywrightAdapter } from "../../adapter/playwright.js";
 import { registerPlaywrightSelectors } from "./custom-selectors.js";

package/lib/support/playwright/custom-selectors.js

@@ -10,6 +10,8 @@ export async function registerPlaywrightSelectors() {
 		registerAttributeSelector(),
 		registerShadowQuerySelector(),
 		registerMeSelector(),
+		registerWidthSelector(),
+		registerHeightSelector(),
 	] );
 }
 
@@ -141,6 +143,116 @@ export function registerShadowQuerySelector() {
 	} ) );
 }
 
+/**
+ * Registers custom selector engine `cg-width` for locating elements whose
+ * rendered width satisfies a numeric constraint.
+ *
+ * Query syntax:  <value>          exact match (px)
+ *                >=<value>        minimum width (px)
+ *                <=<value>        maximum width (px)
+ *
+ * When the engine root is an Element it is tested directly. When the root is
+ * a Document or ShadowRoot all descendant elements are searched instead.
+ */
+export function registerWidthSelector() {
+	return selectors.register( "cg-width", () => ( {
+		// client function, runs in browser, can't reliably use shared code other than what is injected as init script
+		query( root, query ) {
+			const [ , op, value ] = /^(>=|<=)?(\d+(?:\.\d+)?)$/.exec( query ) || [];
+			if ( value == null ) {
+				throw new TypeError( "malformed query for matching elements by width" );
+			}
+
+			const target = parseFloat( value );
+			const test = node => {
+				const actual = node.getBoundingClientRect().width;
+				return op === ">=" ? actual >= target : op === "<=" ? actual <= target : actual === target;
+			};
+
+			if ( typeof root.getBoundingClientRect === "function" ) {
+				return test( root ) ? root : undefined;
+			}
+
+			return Array.from( root.querySelectorAll( "*" ) ).find( test );
+		},
+
+		// client function, runs in browser, can't reliably use shared code other than what is injected as init script
+		queryAll( root, query ) {
+			const [ , op, value ] = /^(>=|<=)?(\d+(?:\.\d+)?)$/.exec( query ) || [];
+			if ( value == null ) {
+				throw new TypeError( "malformed query for matching elements by width" );
+			}
+
+			const target = parseFloat( value );
+			const test = node => {
+				const actual = node.getBoundingClientRect().width;
+				return op === ">=" ? actual >= target : op === "<=" ? actual <= target : actual === target;
+			};
+
+			if ( typeof root.getBoundingClientRect === "function" ) {
+				return test( root ) ? [root] : [];
+			}
+
+			return Array.from( root.querySelectorAll( "*" ) ).filter( test );
+		},
+	} ) );
+}
+
+/**
+ * Registers custom selector engine `cg-height` for locating elements whose
+ * rendered height satisfies a numeric constraint.
+ *
+ * Query syntax:  <value>          exact match (px)
+ *                >=<value>        minimum height (px)
+ *                <=<value>        maximum height (px)
+ *
+ * When the engine root is an Element it is tested directly. When the root is
+ * a Document or ShadowRoot all descendant elements are searched instead.
+ */
+export function registerHeightSelector() {
+	return selectors.register( "cg-height", () => ( {
+		// client function, runs in browser, can't reliably use shared code other than what is injected as init script
+		query( root, query ) {
+			const [ , op, value ] = /^(>=|<=)?(\d+(?:\.\d+)?)$/.exec( query ) || [];
+			if ( value == null ) {
+				throw new TypeError( "malformed query for matching elements by height" );
+			}
+
+			const target = parseFloat( value );
+			const test = node => {
+				const actual = node.getBoundingClientRect().height;
+				return op === ">=" ? actual >= target : op === "<=" ? actual <= target : actual === target;
+			};
+
+			if ( typeof root.getBoundingClientRect === "function" ) {
+				return test( root ) ? root : undefined;
+			}
+
+			return Array.from( root.querySelectorAll( "*" ) ).find( test );
+		},
+
+		// client function, runs in browser, can't reliably use shared code other than what is injected as init script
+		queryAll( root, query ) {
+			const [ , op, value ] = /^(>=|<=)?(\d+(?:\.\d+)?)$/.exec( query ) || [];
+			if ( value == null ) {
+				throw new TypeError( "malformed query for matching elements by height" );
+			}
+
+			const target = parseFloat( value );
+			const test = node => {
+				const actual = node.getBoundingClientRect().height;
+				return op === ">=" ? actual >= target : op === "<=" ? actual <= target : actual === target;
+			};
+
+			if ( typeof root.getBoundingClientRect === "function" ) {
+				return test( root ) ? [root] : [];
+			}
+
+			return Array.from( root.querySelectorAll( "*" ) ).filter( test );
+		},
+	} ) );
+}
+
 /**
  * Registers custom selector for locating current root element itself primarily
  * to feature its combination with other locators.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cepharum/contextual-gherkin",
-	"version": "3.0.0",
+	"version": "4.0.0",
 	"description": "flexible step definitions for Gherkin",
 	"author": "cepharum GmbH <thomas.urban@cepharum.de>",
 	"homepage": "https://cepharum-foss.gitlab.io/contextual-gherkin/",

package/steps/common-helper.js

@@ -11,7 +11,15 @@ Then( "I debug", { timeout: -1 }, debug );
 Then( "I pause", { timeout: -1 }, debug );
 
 // make sure to disconnect the browser after testing
-AfterAll( () => Api.access().browser.disconnect() );
+AfterAll( async() => {
+	try {
+		await Api.access().browser.disconnect();
+	} catch ( cause ) {
+		if ( !cause.missingContextualGherkin ) {
+			throw cause;
+		}
+	}
+} );
 
 After( () => {
 	Api.access().clearHistories();