@cepharum/contextual-gherkin 3.0.0-beta.5 → 3.0.0-beta.6

package/index.d.ts

@@ -751,7 +751,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 ): Context;
+		withAttribute( name: string, value: string|RegExp|boolean ): Context;
 
 		/**
 		 * Limits set of matching elements to those with a named DOM property
@@ -768,7 +768,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|SelectorFn ): Context;
+		withProperty( name: string, value: string|RegExp|boolean|SelectorFn ): Context;
 
 		/**
 		 * Limits set of matching elements to those with a named DOM property
@@ -1000,4 +1000,35 @@ declare module "@cepharum/contextual-gherkin" {
 	type PlaywrightBrowserContextOptions = BrowserContextOptions;
 	type PlaywrightBrowser = Browser;
 	type PlaywrightLocator = Locator;
+
+	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>;
 }

package/index.js

@@ -13,6 +13,8 @@ export * from "./lib/adapter/playwright.js";
 export * from "./lib/context/abstract.js";
 export * from "./lib/context/playwright.js";
 
+export * from "./lib/step-helper.js";
+
 /**
  * Configures test controller to support phrases of contextual Gherkin.
  *

package/lib/api.js

@@ -157,11 +157,12 @@ export class Api {
 	 *       view in case you need a view with a dedicated session.
 	 *
 	 * @param {string} name name of view to provide
+	 * @param {boolean} sharedSession if true, the optionally created view shares a session with current one, otherwise it runs in a different session
 	 */
-	async getViewByName( name = "default" ) {
+	async getViewByName( name = "default", sharedSession = true ) {
 		const view = this.#views.get( name );
 
-		return view == null ? await this.createView( name ) : view;
+		return view == null ? await this.createView( name, sharedSession ) : view;
 	}
 
 	/**
@@ -173,12 +174,13 @@ export class Api {
 	 *       view in case you need a view with a dedicated session.
 	 *
 	 * @param {string} name name of view to provide
+	 * @param {boolean} sharedSession if true, the optionally created view shares a session with current one, otherwise it runs in a different session
 	 */
-	async selectViewByName( name = "default" ) {
+	async selectViewByName( name = "default", sharedSession = true ) {
 		const view = this.#views.get( name );
 
 		if ( view == null ) {
-			return await this.createView( name, true, true );
+			return await this.createView( name, sharedSession, true );
 		}
 
 		this.#currentViewName = name;

package/lib/step-helper.js

@@ -0,0 +1,579 @@
+import { Api } from "./api.js";
+import { stringMessageOperator as sOp } from "../lib/helper.js";
+
+/* eslint-disable spaced-comment */
+
+//#region common helpers
+
+export const actAndTrack = async( cardinal, matches, action, input ) => {
+	const api = Api.access();
+	const target = matches.find( "$" + action, false );
+
+	await api.expect( target.locator, `none or multiple matching $${action} target for selected ${cardinal.word} to ${input == null ? action : `enter '${input}' into`}` )
+		.toHaveCount( 1 );
+
+	// detach matches first as interacting with them might change them in a way
+	// so that the original query isn't finding them anymore (e.g. changing
+	// label of a button on click)
+	const detached = await matches.detach( cardinal.cardinality );
+
+	if ( input == null ) {
+		await target.actions[action]();
+	} else {
+		await target.actions.fill( input );
+	}
+
+	await detached.track( cardinal.word, cardinal.cardinality );
+
+	const wait = Number( process.env.ACTION_WAIT ) || 100;
+	if ( wait > 0 ) {
+		await api.wait( wait );
+	}
+};
+
+//#endregion
+
+
+//#region global querying helpers
+
+/**
+ * Searches for type of elements with a certain label.
+ *
+ * @param {NumberAndWord} cardinal provides cardinal number and word
+ * @returns {Promise<void>} promises step passed
+ */
+export async function globalFind( cardinal ) {
+	const api = Api.access();
+
+	await api
+		.find( cardinal.word )
+		.checkCardinalWord( cardinal );
+}
+
+/**
+ * Searches for element(s) matching a named attribute by value.
+ *
+ * @param {NumberAndWord} cardinal describes what to search
+ * @param {string|RegExp} name name of attribute to match
+ * @param {string|RegExp|boolean} value value of named attribute to match, boolean value to explicitly test for named attribute being truthy or falsy
+ * @return {Promise<void>} promises step passed
+ */
+export async function globalFindByAttribute( cardinal, name, value ) {
+	const api = Api.access();
+
+	await api
+		.find( cardinal.word )
+		.withAttribute( name, value )
+		.checkCardinalWord( cardinal, true, `expected %amount with ${name} ${sOp( value )} ${value}` );
+}
+
+/**
+ * Searches for element(s) matching a named DOM property by value.
+ *
+ * @param {NumberAndWord} cardinal describes what to search
+ * @param {string} name name of DOM property to match
+ * @param {string|boolean} value value of named DOM property to match, or boolean value to explicitly test if property is truthy or falsy
+ * @return {Promise<void>} promises step passed
+ */
+export async function globalFindByProperty( cardinal, name, value ) {
+	const api = Api.access();
+
+	let text;
+
+	if ( typeof value === "boolean" ) {
+		text = `${value ? "not " : ""}${name}`;
+	} else {
+		text = `with ${name} ${sOp( value )} ${value}`;
+	}
+
+	await api
+		.find( cardinal.word )
+		.withProperty( name, value )
+		.checkCardinalWord( cardinal, true, `expected %amount ${text}` );
+}
+
+/**
+ * Searches for element(s) with a named class set.
+ *
+ * @param {NumberAndWord} cardinal describes what to search
+ * @param {string} className name of class to test
+ * @param {boolean} negated inverts the assertion by means of requiring one or all elements of context not to have selected class
+ * @return {Promise<void>} promises step passed
+ */
+export async function globalFindByClass( cardinal, className, negated ) {
+	const api = Api.access();
+	const matches = api
+		.find( cardinal.word )
+		.withListProperty( "classList", className, negated );
+
+	await matches.checkCardinalWord( cardinal, true, `expected %amount ${negated ? "not " : ""}marked as "${className}"` );
+}
+
+/**
+ * Searches for type of elements with a certain label.
+ *
+ * @param {NumberAndWord} cardinal provides cardinal number and word
+ * @param {string} label provides required label of matching element(s)
+ * @param {boolean} partially if true, provided text does not have to match whole content of matching subs
+ * @returns {Promise<void>} promises step passed
+ */
+export async function globalFindByLabel( cardinal, label, partially ) {
+	const api = Api.access();
+
+	await api
+		.find( cardinal.word )
+		.filterBySubsWithText( "$label", "label", label, partially )
+		.checkCardinalWord( cardinal, true, `expected %amount ${partially ? "partially " : ""}labelled with "${label}"` );
+}
+
+/**
+ * Searches for type of elements with a certain label.
+ *
+ * @param {NumberAndWord} cardinal provides cardinal number and word
+ * @param {string} text provides text to be found in eventually matching element(s)
+ * @param {boolean} partially if true, provided text does not have to match whole content of matching subs
+ * @returns {Promise<void>} promises step passed
+ */
+export async function globalFindByTextContent( cardinal, text, partially ) {
+	const api = Api.access();
+
+	await api
+		.find( cardinal.word )
+		.filterBySubsWithText( "$text", false, text, partially )
+		.checkCardinalWord( cardinal, true, `expected %amount ${partially ? "partially " : ""}reading "${text}"` );
+}
+
+//#endregion
+
+
+//#region global action helpers
+
+/**
+ * Searches for element matching a named attribute by value and performs
+ * selected action on it.
+ *
+ * @param {NumberAndWord} cardinal describes what to search
+ * @param {string|RegExp} name name of attribute to match
+ * @param {string|RegExp} value value of named attribute to match
+ * @param {'click'|'hover'|'enter'} action action to perform on found element
+ * @param {string} [input] text to enter into selected field (instead of clicking or hovering)
+ * @return {Promise<void>} promises step passed
+ */
+export async function globalActionByAttribute( cardinal, name, value, action, input ) {
+	const api = Api.access();
+
+	if ( cardinal.cardinality !== "singular" ) {
+		await api.expect( false, `selector is not addressing a single ${cardinal.word} to ${input == null ? action : `enter '${input}' into`}` )
+			.toEqual( true );
+	}
+
+	const matches = api.find( cardinal.word ).withAttribute( name, value );
+
+	await api.expect( matches.locator, `no single matching ${cardinal.word} with attribute ${name} == "${value}" to ${input == null ? action : `enter '${input}' into`}` )
+		.toHaveCount( 1 );
+
+	await actAndTrack( cardinal, matches, action, input );
+}
+
+/**
+ * Searches for element matching a named attribute by value and performs
+ * selected action on it.
+ *
+ * @param {NumberAndWord} cardinal describes what to search
+ * @param {string|RegExp} className class required for match
+ * @param {boolean} negated inverts the assertion by means of requiring one or all elements of context not to have selected class
+ * @param {'click'|'hover'|'enter'} action action to perform on found element
+ * @param {string} [input] text to enter into selected field (instead of clicking or hovering)
+ * @return {Promise<void>} promises step passed
+ */
+export async function globalActionByClass( cardinal, className, negated, action, input ) {
+	const api = Api.access();
+
+	if ( cardinal.cardinality !== "singular" ) {
+		await api.expect( false, `selector is not addressing a single ${cardinal.word} ${negated ? "not " : ""}marked as ${className} to ${input == null ? action : `enter '${input}' into`}` )
+			.toEqual( true );
+	}
+
+	const matches = api
+		.find( cardinal.word )
+		.withListProperty( "classList", className, negated );
+
+	await api.expect( matches.locator, `no single matching ${cardinal.word} ${negated ? "not " : ""}marked as ${className} to ${input == null ? action : `enter '${input}' into`}` )
+		.toHaveCount( 1 );
+
+	await actAndTrack( cardinal, matches, action, input );
+}
+
+/**
+ * Searches for element matching a named DOM property by value and performs
+ * selected action on it.
+ *
+ * @param {NumberAndWord} cardinal describes what to search
+ * @param {string|RegExp} name name of attribute to match
+ * @param {string|RegExp} value value of named attribute to match
+ * @param {'click'|'hover'|'enter'} action action to perform on found element
+ * @param {string} [input] text to enter into selected field (instead of clicking or hovering)
+ * @return {Promise<void>} promises step passed
+ */
+export async function globalActionByProperty( cardinal, name, value, action, input ) {
+	const api = Api.access();
+
+	if ( cardinal.cardinality !== "singular" ) {
+		await api.expect( false, `selector is not addressing a single ${cardinal.word} with property ${name} == "${value}" to ${input == null ? action : `enter '${input}' into`}` )
+			.toEqual( true );
+	}
+
+	const matches = api.find( cardinal.word ).withProperty( name, value );
+
+	await api.expect( matches.locator, `no single matching ${cardinal.word} with property ${name} == "${value}" to ${input == null ? action : `enter '${input}' into`}` )
+		.toHaveCount( 1 );
+
+	await actAndTrack( cardinal, matches, action, input );
+}
+
+/**
+ * Searches for type of element with a certain label and performs selected
+ * action on it.
+ *
+ * @param {NumberAndWord} cardinal provides cardinal number and word
+ * @param {string} label provides required label of matching element(s)
+ * @param {boolean} partially if true, provided text does not have to match whole content of matching subs
+ * @param {'click'|'hover'|'enter'} action action to perform on found element
+ * @param {string} [input] text to enter into selected field (instead of clicking or hovering)
+ * @returns {Promise<void>} promises step passed
+ */
+export async function globalActionByLabel( cardinal, label, partially, action, input ) {
+	const api = Api.access();
+
+	if ( cardinal.cardinality !== "singular" ) {
+		await api.expect( false, `selector is not addressing a single ${cardinal.word} with ${partially ? "partial " : ""}label "${label}" to ${input == null ? action : `enter '${input}' into`}` )
+			.toEqual( true );
+	}
+
+	const matches = api.find( cardinal.word ).filterBySubsWithText( "$label", "label", label, partially );
+
+	await api.expect( matches.locator, `no single matching ${cardinal.word} with ${partially ? "partial " : ""}label "${label}" to ${input == null ? action : `enter '${input}' into`}` )
+		.toHaveCount( 1 );
+
+	await actAndTrack( cardinal, matches, action, input );
+}
+
+/**
+ * Searches for type of element with given text content and performs selected
+ * action on it.
+ *
+ * @param {NumberAndWord} cardinal provides cardinal number and word
+ * @param {string} text provides text to be found in eventually matching element(s)
+ * @param {boolean} partially if true, provided text does not have to match whole content of matching subs
+ * @param {'click'|'hover'|'enter'} action action to perform on found element
+ * @param {string} [input] text to enter into selected field (instead of clicking or hovering)
+ * @returns {Promise<void>} promises step passed
+ */
+export async function globalActionByTextContent( cardinal, text, partially, action, input ) {
+	const api = Api.access();
+
+	if ( cardinal.cardinality !== "singular" ) {
+		await api.expect( false, `selector is not addressing a single ${cardinal.word} ${partially ? "partially " : ""}reading "${text}" to ${input == null ? action : `enter '${input}' into`}` )
+			.toEqual( true );
+	}
+
+	const matches = api.find( cardinal.word ).filterBySubsWithText( "$text", false, text, partially );
+
+	await api.expect( matches.locator, `no single matching ${cardinal.word} ${partially ? "partially " : ""}reading "${text}" to ${input == null ? action : `enter '${input}' into`}` )
+		.toHaveCount( 1 );
+
+	await actAndTrack( cardinal, matches, action, input );
+}
+
+//#endregion
+
+
+//#region local querying helpers
+
+/**
+ * Finds elements in context of containing elements.
+ *
+ * @param {ContextualWord} phrase describes context of search
+ * @param {NumberAndWord} cardinal describes what to search
+ * @return {Promise<void>} promises step passed
+ */
+export async function localFind( phrase, cardinal ) {
+	const api = Api.access();
+	const context = api.getContextFor( phrase );
+
+	await context
+		.find( cardinal.word )
+		.checkCardinalWord( cardinal );
+}
+
+/**
+ * Finds elements in context of containing elements matching a named attribute
+ * by value.
+ *
+ * @param {ContextualWord} phrase describes context of search
+ * @param {NumberAndWord} cardinal describes what to search
+ * @param {string|RegExp} name name of attribute to match
+ * @param {string|RegExp} value value of named attribute to match
+ * @return {Promise<void>} promises step passed
+ */
+export async function localFindByAttribute( phrase, cardinal, name, value ) {
+	const api = Api.access();
+	const context = api.getContextFor( phrase );
+
+	await context
+		.find( cardinal.word )
+		.withAttribute( name, value )
+		.checkCardinalWord( cardinal, true, `expected %amount with ${name} ${sOp( value )} ${value}` );
+}
+
+/**
+ * Finds elements in context of containing elements matching a named DOM
+ * property by value.
+ *
+ * @param {ContextualWord} phrase describes context of search
+ * @param {NumberAndWord} cardinal describes what to search
+ * @param {string} name name of DOM property to match
+ * @param {string|boolean} value value of named DOM property to match, or boolean to explicitly test named property for being truthy or falsy
+ * @return {Promise<void>} promises step passed
+ */
+export async function localFindByProperty( phrase, cardinal, name, value ) {
+	const api = Api.access();
+	const context = api.getContextFor( phrase );
+	let text;
+
+	if ( typeof value === "boolean" ) {
+		text = `${value ? "" : "not "}${name}`;
+	} else {
+		text = `with ${name} ${value instanceof RegExp ? "matching" : "equals"} ${value}`;
+	}
+
+	await context
+		.find( cardinal.word )
+		.withProperty( name, value )
+		.checkCardinalWord( cardinal, true, `expected %amount ${text}` );
+}
+
+/**
+ * Finds elements in context of containing elements with named class.
+ *
+ * @param {ContextualWord} phrase describes context of search
+ * @param {NumberAndWord} cardinal describes what to search
+ * @param {string} className name of class to check
+ * @param {boolean} negated inverts the assertion by means of requiring one or all elements of context not to have selected class
+ * @return {Promise<void>} promises step passed
+ */
+export async function localFindByClass( phrase, cardinal, className, negated ) {
+	const api = Api.access();
+	const context = api.getContextFor( phrase );
+	const matches = context.find( cardinal.word );
+
+	await matches
+		.withListProperty( "classList", className, negated )
+		.checkCardinalWord( cardinal, true, `expected %amount ${negated ? "not " : ""}marked as "${className}"` );
+}
+
+/**
+ * Finds elements in context of containing elements with a given label.
+ *
+ * @param {ContextualWord} phrase describes context of search
+ * @param {NumberAndWord} cardinal describes what to search
+ * @param {string} label expected label of item(s) to find
+ * @param {boolean} partially if true, provided text does not have to match whole content of matching subs
+ * @return {Promise<void>} promises step passed
+ */
+export async function localFindByLabel( phrase, cardinal, label, partially ) {
+	const api = Api.access();
+	const context = api.getContextFor( phrase );
+
+	await context
+		.find( cardinal.word )
+		.filterBySubsWithText( "$label", "label", label, partially )
+		.checkCardinalWord( cardinal, true, `expected %amount ${partially ? "partially " : ""}labelled with "${label}"` );
+}
+
+/**
+ * Finds elements in context of containing elements containing given text.
+ *
+ * @param {ContextualWord} phrase describes context of search
+ * @param {NumberAndWord} cardinal describes what to search
+ * @param {string} text provides expected text content of item(s) to find
+ * @param {boolean} partially if true, provided text does not have to match whole content of matching subs
+ * @return {Promise<void>} promises step passed
+ */
+export async function localFindByTextContent( phrase, cardinal, text, partially ) {
+	const api = Api.access();
+	const context = api.getContextFor( phrase );
+
+	await context
+		.find( cardinal.word )
+		.filterBySubsWithText( "$text", false, text, partially )
+		.checkCardinalWord( cardinal, true, `expected %amount ${partially ? "partially " : ""}reading "${text}"` );
+}
+
+//#endregion
+
+
+//#region local action helpers
+
+/**
+ * Searches for type of element in current context and performs selected action
+ * on it.
+ *
+ * @param {ContextualWord} phrase description of element to be clicked.
+ * @param {'click'|'hover'|'enter'} action action to perform on found element
+ * @param {string} [input] text to enter into selected field (instead of clicking or hovering)
+ * @returns {Promise<void>} promises element clicked
+ */
+export async function localAction( phrase, action, input ) {
+	const api = Api.access();
+	const context = api.getContextFor( phrase );
+
+	await api.expect( context.locator, `no single matching ${phrase.word} to ${input == null ? action : `enter '${input}' into`}` )
+		.toHaveCount( 1 );
+
+	const target = context.find( "$" + action, false );
+
+	await api.expect( target.locator, `no single matching $${action} target for selected ${phrase.word} to ${input == null ? action : `enter '${input}' into`}` )
+		.toHaveCount( 1 );
+
+	// detach matches first as interacting with them might change them in a way
+	// so that the original query isn't finding them anymore (e.g. changing
+	// label of a button on click)
+	const detached = await context.detach( phrase.targetCardinality );
+
+	if ( input == null ) {
+		await target.actions[action]();
+	} else {
+		await target.actions.fill( input );
+	}
+
+	if ( phrase.isRefining ) {
+		await detached.track( phrase.word, phrase.targetCardinality );
+	}
+
+	const wait = Number( process.env.ACTION_WAIT ) || 100;
+	if ( wait > 0 ) {
+		await api.wait( wait );
+	}
+}
+
+//#endregion
+
+
+//#region local assertion helpers
+
+/**
+ * Checks if some or all elements of an addressed match have a named attribute
+ * matching some expected value.
+ *
+ * @param {ContextualWord} phrase description of previous match to check
+ * @param {boolean} all if true, all matching elements have to match named attribute's expected value
+ * @param {string} name name of attribute to check with either matching element
+ * @param {string} value expected value of named attribute per matching element
+ * @returns {Promise<void>} promises check passed
+ */
+export async function localStateByAttribute( phrase, all, name, value ) {
+	const api = Api.access();
+	const context = api.getContextFor( phrase );
+	const filtered = context.withAttribute( name, value );
+
+	await context.checkFilteredInContext( filtered, phrase, all );
+}
+
+/**
+ * Checks if all elements of an addressed match have a named property matching
+ * some expected value.
+ *
+ * @param {ContextualWord} phrase description of previous match to check
+ * @param {boolean} all if true, all matching elements have to match named attribute's expected value
+ * @param {string} name name of DOM property to check on either matching element
+ * @param {string|RegExp|boolean} value expected value of named property per matching element
+ * @returns {Promise<void>} promises check passed
+ */
+export async function localStateByProperty( phrase, all, name, value ) {
+	const api = Api.access();
+	const context = api.getContextFor( phrase );
+	const filtered = context.withProperty( name, value );
+
+	await context.checkFilteredInContext( filtered, phrase, all );
+}
+
+/**
+ * Asserts if selected element(s) has/have given class or not.
+ *
+ * @param {ContextualWord} phrase describes context of search
+ * @param {boolean} all if true, all matching elements have to match named attribute's expected value
+ * @param {string} className name of class to check
+ * @param {boolean} negated inverts the assertion by means of requiring one or all elements of context not to have selected class
+ * @return {Promise<void>} promises step passed
+ */
+export async function localStateByClass( phrase, all, className, negated ) {
+	const api = Api.access();
+	const context = api.getContextFor( phrase );
+	const filtered = context.withListProperty( "classList", className, negated );
+
+	await context.checkFilteredInContext( filtered, phrase, all );
+}
+
+/**
+ * Checks if an addressed match of a previously tracked search contains a given
+ * text.
+ *
+ * @param {ContextualWord} phrase description of previous match to check
+ * @param {string} text expected text found in elements of selected match
+ * @param {boolean} partially if true, provided text does not have to match whole content of matching subs
+ * @returns {Promise<void>} promises check passed
+ */
+export async function localStateByLabel( phrase, text, partially ) {
+	const api = Api.access();
+	const context = api.getContextFor( phrase );
+	const cardinal = phrase.asCardinalWord( await context.matchCount() );
+
+	await context
+		.filterBySubsWithText( "$label", "label", text, partially )
+		.checkCardinalWord( cardinal, phrase.isRefining, `expected %amount labelled with "${text}"` );
+}
+
+/**
+ * Checks if an addressed match of a previously tracked search contains a given
+ * text.
+ *
+ * @param {ContextualWord} phrase description of previous match to check
+ * @param {string} text expected text found in elements of selected match
+ * @param {boolean} partially if true searched elements may partially contain provided text to be considered a match
+ * @returns {Promise<void>} promises check passed
+ */
+export async function localStateByTextContent( phrase, text, partially ) {
+	const api = Api.access();
+	const context = api.getContextFor( phrase );
+	const cardinal = phrase.asCardinalWord( await context.matchCount() );
+
+	await context
+		.filterBySubsWithText( "$text", false, text, partially )
+		.checkCardinalWord( cardinal, phrase.isRefining, `expected %amount ${partially ? "partially " : ""}reading "${text}"` );
+}
+
+/**
+ * Checks if some contextual elements exist or are missing explicitly.
+ *
+ * @param {ContextualWord} phrase description of previous match to check
+ * @param {boolean} mustExist if true, described contextual element has to exist to pass, otherwise it has to be missing
+ * @returns {Promise<void>} promises check passed
+ */
+export async function localStateExists( phrase, mustExist ) {
+	const api = Api.access();
+	const context = api.getContextFor( phrase );
+
+	if ( mustExist ) {
+		// FIXME might pass unintentionally if just one of several elements to be tested exists
+		await api.expect( context.locator ).not.toHaveCount( 0 );
+
+		if ( phrase.isRefining ) {
+			await context.track( phrase.word, phrase.targetCardinality );
+		}
+	} else {
+		await api.expect( context.locator ).toHaveCount( 0 );
+	}
+}
+
+//#endregion

package/package.json

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