@cepharum/contextual-gherkin 1.2.1 → 1.2.3

package/cli.js

@@ -6,6 +6,7 @@ const Path = require( "node:path" );
 const os = require( "node:os" );
 
 const semver = require( "semver" );
+const { getShellConfigurationSync, quote } = require( "@cepharum/quoting-db" );
 
 const cgFolder = "./node_modules/@cepharum/contextual-gherkin";
 const isWindows = os.platform() === "win32";
@@ -59,17 +60,48 @@ const isWindows = os.platform() === "win32";
 	const patterns = [];
 	const options = {};
 	const passedOptions = [];
+	let expectOptions = true;
 
 	for ( let i = 2; i < process.argv.length; i++ ) {
 		const arg = process.argv[i];
 
+		if ( arg === "--" && expectOptions ) {
+			expectOptions = false;
+			continue;
+		}
+
 		if ( arg.startsWith( "-" ) ) {
-			const [ option, ...parts ] = arg.split( "=" );
+			let [ option, ...parts ] = arg.split( "=" ); // eslint-disable-line prefer-const
+
+			switch ( expectOptions ? option : null ) {
+				case "-E" :
+				case "--env" :
+					if ( parts.length > 0 ) {
+						console.error( `use separate argument to define environment variable with ${option}` );
+						process.exit( 1 );
+					}
 
-			switch ( option ) {
+					if ( ++i < process.argv.length ) {
+						const value = process.argv[i].trim();
+						const split = value.indexOf( "=" );
+
+						if ( split < 0 ) {
+							console.error( `missing value for defined environment variable ${value}` );
+							process.exit( 1 );
+						}
+
+						( options.env ??= {} )[value.substring( 0, split )] = value.substring( split + 1 );
+					} else {
+						console.error( `found --${name} option without value` );
+						process.exit( 1 );
+					}
+
+					break;
+
+				case "--env-file" :
+				case "--features" :
 				case "--folder" :
-				case "--steps" :
-				case "--features" : {
+				case "--steps" : {
 					const name = option.slice( 2 );
 
 					if ( parts.length > 0 ) {
@@ -114,10 +146,79 @@ const isWindows = os.platform() === "win32";
 	}
 
 
+	// pre-compile environment
+	let env = {
+		...process.env,
+		...options.env
+	};
+
+
+	// read optionally selected environment file
+	let content;
+
+	try {
+		content = ( await File.promises.readFile( options["env-file"], { encoding: "utf-8" } ) ).trim();
+	} catch ( cause ) {
+		if ( cause.code !== "ENOENT" && options["env-file"] != null ) {
+			throw cause;
+		}
+	}
+
+	if ( content ) {
+		options["env-file"] = {};
+
+		for ( const line of content.split( /\r?\n/ ) ) {
+			const trimmed = line.trim();
+
+			if ( trimmed === "" || trimmed[0] === "#" || trimmed[0] === ";" ) {
+				continue;
+			}
+
+			let [ name, ...value ] = trimmed.split( "=" );
+
+			name = name.trim();
+			value = value.join( "=" ).trim();
+
+			if ( value.startsWith( "'" ) && value.endsWith( "'" ) ) {
+				value = value.substring( 1, value.length - 1 );
+			} else {
+				value = value.replace( /^"(.*)"$/, "$1" )
+					.replace( /\$(?:\{\s*([a-z0-9_]+)\s*}|([a-z0-9_]+))/g, ( _, a, b ) => env[a ?? b] ?? "" );
+			}
+
+			env[name.trim()] = options["env-file"][name.trim()] = value;
+		}
+	}
+
+
+	// recompile environment
+	env = {
+		...process.env,
+		...options["env-file"],
+		...options.env
+	};
+
+	const proxy = new Proxy( env, {
+		get( target, p ) {
+			if ( target.hasOwnProperty( p ) ) {
+				return target[p];
+			}
+
+			for ( const [ key, value ] of Object.entries( target ) ) {
+				if ( key.toLowerCase() === p.toLowerCase() ) {
+					return value;
+				}
+			}
+
+			return undefined;
+		}
+	} );
+
+
 	// inspect local installation of npm to pick sanitizer for passed parameters
 	let npm;
 
-	for ( const path of process.env.PATH.split( Path.delimiter ) ) {
+	for ( const path of proxy.PATH.split( Path.delimiter ) ) {
 		const candidate = Path.resolve( path, isWindows ? "npm.cmd" : "npm" );
 		const npmStat = await stat( candidate ); // eslint-disable-line no-await-in-loop
 
@@ -148,24 +249,24 @@ const isWindows = os.platform() === "win32";
 	}
 
 	if ( spawnOptions.shell ) {
-		const { getShellConfiguration, quote } = await import( "@cepharum/quoting-db" );
-		const configuration = await getShellConfiguration();
+		const configuration = getShellConfigurationSync( spawnOptions.shell );
 
 		sanitizer = argument => quote( argument, configuration );
 	}
 
+
 	// invoke gherkin-testcafe and provide all required information
 	const child = spawn( "npm", [
 		"exec",
 		"gherkin-testcafe",
 		"--",
-		`${( process.env.E2E_BROWSER && sanitizer( process.env.E2E_BROWSER ) ) || ( isWindows ? "chrome" : "chromium:headless" )}`,
+		`${( env.E2E_BROWSER && sanitizer( env.E2E_BROWSER ) ) || ( isWindows ? "chrome" : "chromium:headless" )}`,
 		`${cgFolder}/steps/**/*.js`,
 		...patterns.map( sanitizer ),
 		"--param-type-registry-file",
 		`${cgFolder}/steps/types.js`,
 		...passedOptions.map( sanitizer )
-	], { stdio: "inherit", ...spawnOptions } );
+	], { stdio: "inherit", ...spawnOptions, env } );
 
 	child.once( "error", console.error );
 	child.once( "exit", process.exit );

package/lib/context.js

@@ -256,27 +256,33 @@ class Context {
 	 *       node's matches, only.
 	 *
 	 * @param {string|RegExp} name name of attribute to look up per matching element
-	 * @param {string|RegExp} value value expected in named attribute of either element
+	 * @param {string|RegExp|function(any):boolean} value value expected in named attribute of either element, callback for custom test of attribute value
 	 * @returns {Promise<Context>} promises another node listing those matches of current node matching named attribute
 	 */
-	withAttribute( name, value ) {
-		if ( !this.matches ) {
+	async withAttribute( name, value ) {
+		if ( ! await this.matches.count ) {
 			throw new TypeError( "there are no matches to filter" );
 		}
 
-		const { query } = this.getSelector( "@" + name, false ) ?? {};
-		const matches = typeof value === "function" ? this.matches.filter( node => {
-			const actual = node.attributes.getNamedItem( name );
+		const { query: nameQuery } = this.getSelector( "@" + name, false ) ?? {};
+		const ___name = nameQuery ?? name;
+		const ___value = value;
 
-			return value( actual == null ? undefined : actual.value );
-		}, { name: query ?? name, value } ) : this.matches.withAttribute( query ?? name, value );
+		return this.filterBySubsWithFn( "$" + name, false, node => {
+			const expected = ___value;
+			const attribute = node.attributes.getNamedItem( ___name );
+			const actual = attribute == null ? undefined : attribute.value;
 
-		return Promise.resolve( new this.constructor( this.testController, this, this.api, {
-			matches,
-			type: this.type,
-			selectors: this.selectors,
-			cardinality: this.cardinality,
-		} ) );
+			if ( typeof expected === "function" && expected( actual ) ) {
+				return true;
+			}
+
+			if ( expected instanceof RegExp && expected.test( actual ) ) {
+				return true;
+			}
+
+			return expected === actual;
+		}, { ___name, ___value } );
 	}
 
 	/**
@@ -287,37 +293,32 @@ class Context {
 	 *       node's matches, only.
 	 *
 	 * @param {string} name name of DOM property to look up per matching element
-	 * @param {string|RegExp|function(any):boolean} value value expected in named DOM property of either element, callback for testing individual property value
+	 * @param {string|RegExp|function(any):boolean} value value expected in named DOM property of either element, callback for custom test of property value
 	 * @returns {Promise<Context>} promises another node listing those matches of current node matching named property
 	 */
-	withProperty( name, value ) {
-		if ( !this.matches ) {
+	async withProperty( name, value ) {
+		if ( ! await this.matches.count ) {
 			throw new TypeError( "there are no matches to filter" );
 		}
 
-		const { query: _name } = this.getSelector( "#" + name, false ) ?? {};
+		const { query: nameQuery } = this.getSelector( "#" + name, false ) ?? {};
+		const ___name = nameQuery ?? name;
+		const ___value = value;
 
-		const matches = this.matches.filter( node => {
-			const expected = value;
-			const actual = node[name];
+		return this.filterBySubsWithFn( "$" + name, false, node => {
+			const expected = ___value;
+			const actual = node[___name];
 
-			if ( typeof expected === "function" ) {
-				return expected( actual );
+			if ( typeof expected === "function" && expected( actual ) ) {
+				return true;
 			}
 
-			if ( expected instanceof RegExp ) {
-				return expected.test( actual );
+			if ( expected instanceof RegExp && expected.test( actual ) ) {
+				return true;
 			}
 
 			return expected === actual;
-		}, { name: _name ?? name, value } );
-
-		return Promise.resolve( new this.constructor( this.testController, this, this.api, {
-			matches,
-			type: this.type,
-			selectors: this.selectors,
-			cardinality: this.cardinality,
-		} ) );
+		}, { ___name, ___value } );
 	}
 
 	/**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cepharum/contextual-gherkin",
-	"version": "1.2.1",
+	"version": "1.2.3",
 	"description": "flexible step definitions for Gherkin",
 	"author": "cepharum GmbH <thomas.urban@cepharum.de>",
 	"homepage": "https://cepharum-foss.gitlab.io/contextual-gherkin/",
@@ -12,7 +12,7 @@
 	},
 	"keywords": [],
 	"dependencies": {
-		"@cepharum/quoting-db": "^1.0.0",
+		"@cepharum/quoting-db": "^1.2.0",
 		"pluralize": "^8.0.0",
 		"semver": "^7.5.0"
 	},

package/steps/global-action.js

@@ -5,8 +5,8 @@ const actAndTrack = async( testController, cardinal, refined, action, input ) =>
 	const target = await refined.find( "$" + action, false );
 	const targetCount = await target.matches.count;
 
-	await testController.expect( targetCount ).gt( 0, `there is no $${action} target for selected ${cardinal.word} to ${input == null ? action : "enter text into"}` ); // eslint-disable-line max-len
-	await testController.expect( targetCount ).eql( 1, `there is no single $${action} target for selected ${cardinal.word} to ${input == null ? action : "enter text into"}` ); // eslint-disable-line max-len
+	await testController.expect( targetCount ).gt( 0, `there is no $${action} target for selected ${cardinal.word} to ${input == null ? action : `enter '${input}' into`}` ); // eslint-disable-line max-len
+	await testController.expect( targetCount ).eql( 1, `there is no single $${action} target for selected ${cardinal.word} to ${input == null ? action : `enter '${input}' into`}` ); // eslint-disable-line max-len
 
 	await refined.detach();
 
@@ -44,7 +44,7 @@ When( "I enter {string-or-word} into {cardinal-word} named {text-or-regexp}", (
  * @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'} action action to perform on found element
+ * @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
  */
@@ -54,11 +54,16 @@ async function globalActionByAttribute( testController, cardinal, name, value, a
 	}
 
 	const matches = await Api.access( testController ).find( cardinal.word );
+
+	if ( cardinal.cardinality !== "singular" ) {
+		await testController.expect( false ).eql( true, `selector is not addressing a single ${cardinal.word} to ${input == null ? action : `enter '${input}' into`}` ); // eslint-disable-line max-len
+	}
+
 	const refined = await matches.withAttribute( name, value );
 	const matchCount = await refined.matches.count;
 
-	await testController.expect( matchCount ).gt( 0, `there is no matching ${cardinal.word} with attribute ${name} == "${value}" to ${input == null ? action : "enter text into"}` );
-	await testController.expect( matchCount ).eql( 1, `there is no single matching ${cardinal.word} with attribute ${name} == "${value}" to ${input == null ? action : "enter text into"}` ); // eslint-disable-line max-len
+	await testController.expect( matchCount ).gt( 0, `there is no matching ${cardinal.word} with attribute ${name} == "${value}" to ${input == null ? action : `enter '${input}' into`}` ); // eslint-disable-line max-len
+	await testController.expect( matchCount ).eql( 1, `there is no single matching ${cardinal.word} with attribute ${name} == "${value}" to ${input == null ? action : `enter '${input}' into`}` ); // eslint-disable-line max-len
 
 	await actAndTrack( testController, cardinal, refined, action, input );
 }
@@ -79,7 +84,7 @@ When( "I enter {string-or-word} into {cardinal-word} not marked/tagged as {word}
  * @param {TestController} testController exposes test controller
  * @param {NumberAndWord} cardinal describes what to search
  * @param {string|RegExp} className class required for match
- * @param {'click'|'hover'} action action to perform on found element
+ * @param {'click'|'hover'|'enter'} action action to perform on found element
  * @param {boolean} negated inverts the assertion by means of requiring one or all elements of context not to have selected class
  * @param {string} input text to enter into selected field (instead of clicking or hovering)
  * @return {Promise<void>} promises step passed
@@ -90,12 +95,17 @@ async function globalActionByClass( testController, cardinal, className, action,
 	}
 
 	const matches = await Api.access( testController ).find( cardinal.word );
+
+	if ( cardinal.cardinality !== "singular" ) {
+		await testController.expect( false ).eql( true, `selector is not addressing a single ${cardinal.word} ${negated ? "not " : ""}marked as ${className} to ${input == null ? action : `enter '${input}' into`}` ); // eslint-disable-line max-len
+	}
+
 	const { query: property } = matches.getSelector( "#classList", "classList" );
-	const refined = await matches.filterFn( node => node?.[property]?.contains( className ) ^ negated, { property, className, negated } );
+	const refined = await matches.filterBySubsWithFn( "$classList", false, node => node?.[property]?.contains( className ) ^ negated, { property, className, negated } );
 	const matchCount = await refined.matches.count;
 
-	await testController.expect( matchCount ).gt( 0, `there is no matching ${cardinal.word} ${negated ? "not " : ""}marked as ${className} to ${input == null ? action : "enter text into"}` );
-	await testController.expect( matchCount ).eql( 1, `there is no single matching ${cardinal.word} ${negated ? "not " : ""}marked as ${className} to ${input == null ? action : "enter text into"}` );
+	await testController.expect( matchCount ).gt( 0, `there is no matching ${cardinal.word} ${negated ? "not " : ""}marked as ${className} to ${input == null ? action : `enter '${input}' into`}` );
+	await testController.expect( matchCount ).eql( 1, `there is no single matching ${cardinal.word} ${negated ? "not " : ""}marked as ${className} to ${input == null ? action : `enter '${input}' into`}` );
 
 	await actAndTrack( testController, cardinal, refined, action, input );
 }
@@ -114,7 +124,7 @@ When( "I enter {string-or-word} into {cardinal-word} with value {text-or-regexp}
  * @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'} action action to perform on found element
+ * @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
  */
@@ -124,11 +134,16 @@ async function globalActionByProperty( testController, cardinal, name, value, ac
 	}
 
 	const matches = await Api.access( testController ).find( cardinal.word );
+
+	if ( cardinal.cardinality !== "singular" ) {
+		await testController.expect( false ).eql( true, `selector is not addressing a single ${cardinal.word} with property ${name} == "${value}" to ${input == null ? action : `enter '${input}' into`}` ); // eslint-disable-line max-len
+	}
+
 	const refined = await matches.withProperty( name, value );
 	const matchCount = await refined.matches.count;
 
-	await testController.expect( matchCount ).gt( 0, `there is no matching ${cardinal.word} with property ${name} == "${value}" to ${input == null ? action : "enter text into"}` );
-	await testController.expect( matchCount ).eql( 1, `there is no single matching ${cardinal.word} with property ${name} == "${value}" to ${input == null ? action : "enter text into"}` ); // eslint-disable-line max-len
+	await testController.expect( matchCount ).gt( 0, `there is no matching ${cardinal.word} with property ${name} == "${value}" to ${input == null ? action : `enter '${input}' into`}` ); // eslint-disable-line max-len
+	await testController.expect( matchCount ).eql( 1, `there is no single matching ${cardinal.word} with property ${name} == "${value}" to ${input == null ? action : `enter '${input}' into`}` ); // eslint-disable-line max-len
 
 	await actAndTrack( testController, cardinal, refined, action, input );
 }
@@ -156,7 +171,7 @@ When( "I enter {string-or-word} into {cardinal-word} partially labelled with {te
  * @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'} action action to perform on found element
+ * @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
  */
@@ -166,11 +181,16 @@ async function globalActionByLabel( testController, cardinal, label, partially,
 	}
 
 	const matches = await Api.access( testController ).find( cardinal.word );
+
+	if ( cardinal.cardinality !== "singular" ) {
+		await testController.expect( false ).eql( true, `selector is not addressing a single ${cardinal.word} with ${partially ? "partial " : ""}label "${label}" to ${input == null ? action : `enter '${input}' into`}` ); // eslint-disable-line max-len
+	}
+
 	const refined = await matches.filterBySubsWithText( "$label", "label", label, partially );
 	const matchCount = await refined.matches.count;
 
-	await testController.expect( matchCount ).gt( 0, `there is no matching ${cardinal.word} with ${partially ? "partial " : ""}label "${label}" to ${input == null ? action : "enter text into"}` );
-	await testController.expect( matchCount ).eql( 1, `there is no single matching ${cardinal.word} with ${partially ? "partial " : ""}label "${label}" to ${input == null ? action : "enter text into"}` );
+	await testController.expect( matchCount ).gt( 0, `there is no matching ${cardinal.word} with ${partially ? "partial " : ""}label "${label}" to ${input == null ? action : `enter '${input}' into`}` );
+	await testController.expect( matchCount ).eql( 1, `there is no single matching ${cardinal.word} with ${partially ? "partial " : ""}label "${label}" to ${input == null ? action : `enter '${input}' into`}` );
 
 	await actAndTrack( testController, cardinal, refined, action, input );
 }
@@ -198,7 +218,7 @@ When( "I enter {string-or-word} into {cardinal-word} with partial text {text-or-
  * @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'} action action to perform on found element
+ * @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
  */
@@ -208,11 +228,16 @@ async function globalActionByTextContent( testController, cardinal, text, partia
 	}
 
 	const matches = await Api.access( testController ).find( cardinal.word );
+
+	if ( cardinal.cardinality !== "singular" ) {
+		await testController.expect( false ).eql( true, `selector is not addressing a single ${cardinal.word} ${partially ? "partially " : ""}reading "${text}" to ${input == null ? action : `enter '${input}' into`}` ); // eslint-disable-line max-len
+	}
+
 	const refined = await matches.filterBySubsWithText( "$text", false, text, partially );
 	const matchCount = await refined.matches.count;
 
-	await testController.expect( matchCount ).gt( 0, `there is no matching ${cardinal.word} ${partially ? "partially " : ""}reading "${text}" to ${input == null ? action : "enter text into"}` );
-	await testController.expect( matchCount ).eql( 1, `there is no single matching ${cardinal.word} ${partially ? "partially " : ""}reading "${text}" to ${input == null ? action : "enter text into"}` );
+	await testController.expect( matchCount ).gt( 0, `there is no matching ${cardinal.word} ${partially ? "partially " : ""}reading "${text}" to ${input == null ? action : `enter '${input}' into`}` );
+	await testController.expect( matchCount ).eql( 1, `there is no single matching ${cardinal.word} ${partially ? "partially " : ""}reading "${text}" to ${input == null ? action : `enter '${input}' into`}` );
 
 	await actAndTrack( testController, cardinal, refined, action, input );
 }

package/steps/global-find.js

@@ -94,7 +94,7 @@ async function globalFindByClass( testController, cardinal, className, negated )
 
 	const matches = await Api.access( testController ).find( cardinal.word );
 	const { query: property } = matches.getSelector( "#classList", "classList" );
-	const refined = await matches.filterFn( node => node?.[property]?.contains( className ) ^ negated, { property, className, negated } );
+	const refined = await matches.filterBySubsWithFn( "$classList", false, node => node?.[property]?.contains( className ) ^ negated, { property, className, negated } );
 
 	await refined.checkCardinalWord( cardinal, true, `${negated ? "not " : ""}marked as "${className}"` );
 }

package/steps/local-action.js

@@ -25,14 +25,14 @@ async function localAction( testController, phrase, action, input ) {
 	const context = await Api.access( testController ).getContextFor( phrase );
 	const matchCount = await context.matches.count;
 
-	await testController.expect( matchCount ).gt( 0, `there is no ${phrase.word} to ${input == null ? action : "enter text into"}` );
-	await testController.expect( matchCount ).eql( 1, `there is no single ${phrase.word} to ${input == null ? action : "enter text into"}` );
+	await testController.expect( matchCount ).gt( 0, `there is no ${phrase.word} to ${input == null ? action : `enter '${input}' into`}` );
+	await testController.expect( matchCount ).eql( 1, `there is no single ${phrase.word} to ${input == null ? action : `enter '${input}' into`}` );
 
 	const target = await context.find( "$" + action, false );
 	const targetCount = await target.matches.count;
 
-	await testController.expect( targetCount ).gt( 0, `there is no $${action} target for selected ${phrase.word} to ${input == null ? action : "enter text into"}` ); // eslint-disable-line max-len
-	await testController.expect( targetCount ).eql( 1, `there is no single $${action} target for selected ${phrase.word} to ${input == null ? action : "enter text into"}` ); // eslint-disable-line max-len
+	await testController.expect( targetCount ).gt( 0, `there is no $${action} target for selected ${phrase.word} to ${input == null ? action : `enter '${input}' into`}` ); // eslint-disable-line max-len
+	await testController.expect( targetCount ).eql( 1, `there is no single $${action} target for selected ${phrase.word} to ${input == null ? action : `enter '${input}' into`}` ); // eslint-disable-line max-len
 
 	await context.detach();
 

package/steps/local-find.js

@@ -101,7 +101,7 @@ async function localFindByClass( testController, phrase, cardinal, className, ne
 	const context = await Api.access( testController ).getContextFor( phrase );
 	const matches = await context.find( cardinal.word );
 	const { query: property } = matches.getSelector( "#classList", "classList" );
-	const refined = await matches.filterFn( node => node?.[property]?.contains( className ) ^ negated, { property, className, negated } );
+	const refined = await matches.filterBySubsWithFn( "$classList", false, node => node?.[property]?.contains( className ) ^ negated, { property, className, negated } );
 
 	await refined.checkCardinalWord( cardinal, true, `${negated ? "not " : ""}marked as "${className}"` );
 }

package/steps/local-state.js

@@ -79,7 +79,7 @@ async function localStateByClass( testController, phrase, all, className, negate
 
 	const context = await Api.access( testController ).getContextFor( phrase );
 	const { query: property } = context.getSelector( "#classList", "classList" );
-	const filtered = await context.filterFn( node => node?.[property]?.contains( className ) ^ negated, { property, className, negated } );
+	const filtered = await context.filterBySubsWithFn( "$classList", false, node => node?.[property]?.contains( className ) ^ negated, { property, className, negated } );
 
 	await context.checkFilteredInContext( filtered, phrase, all );
 }