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

package/index.d.ts

@@ -18,17 +18,24 @@ declare module "@cepharum/contextual-gherkin" {
 	 * Inserts or augments current runtime's instance of contextual-gherkin or
 	 * returns the most recently instance injected that way.
 	 *
-	 * @param configuration runtime configuration of instance to create and inject into test controller, omit for reading instance, only
+	 * Provided configuration may differ between invocations causing a previous
+	 * configuration to be augmented. A browser adapter must be identical on
+	 * succeeding invocations or should be omitted in follow-up invocations.
+	 *
+	 * When omitting both configuration and a browser adapter, a promise for
+	 * some previously configured instance is returned.
+	 *
+	 * @param configuration runtime configuration of instance to create
 	 * @param adapter interface for interacting with a browser instance
-	 * @returns instance of contextual-gherkin injected into test controller most recently (which might be just now)
+	 * @returns promise for instance of contextual-gherkin
 	 */
-	function ContextualGherkin(configuration?: Configuration, adapter?: BrowserAdapter): Api;
+	async 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 = AbstractContext> {
+	class Api<B = BrowserAdapter<C, A>, C = AbstractContext, A = Assertions> {
 		/**
 		 * Creates singleton instance of contextual-gherkin API in current
 		 * runtime on first invocation or augments configuration of existing
@@ -43,7 +50,7 @@ declare module "@cepharum/contextual-gherkin" {
 		 * Provides singleton instance of current runtime's contextual-gherkin
 		 * API for interacting with content of one or more browser views.
 		 */
-		static access<BA = BrowserAdapter, AC = AbstractContext>(): Api<BA, AS, AC>;
+		static access<BA = B, AC = C, AS = A>(): Api<BA, AC, AS>;
 
 		/**
 		 * Exposes normalized configuration of contextual-gherkin.
@@ -66,7 +73,7 @@ declare module "@cepharum/contextual-gherkin" {
 		 * Exposes assertions library for assessing state of contexts addressing
 		 * elements in a document.
 		 */
-		expect: Expect;
+		expect: A;
 
 		/**
 		 * Fetches view considered current one.
@@ -226,7 +233,7 @@ declare module "@cepharum/contextual-gherkin" {
 	 * Describes interface for interacting with a framework actually controlling
 	 * browsers, inspecting documents and performing actions on its content.
 	 */
-	abstract class BrowserAdapter<C = AbstractContext> {
+	abstract class BrowserAdapter<C = AbstractContext, A = Assertions> {
 		/**
 		 * Creates (another) view for presenting documents, querying and
 		 * interacting with their elements.
@@ -254,7 +261,7 @@ declare module "@cepharum/contextual-gherkin" {
 		/**
 		 * Provides assertions library for assessing state of elements.
 		 */
-		async getAssertions(): Promise<() => Expect>;
+		async getAssertions(): Promise<() => A>;
 	}
 
 	/**
@@ -744,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
@@ -761,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
@@ -856,6 +863,8 @@ declare module "@cepharum/contextual-gherkin" {
 	 */
 	type ContextFramework = "playwright";
 
+	type Assertions = Expect;
+
 	/**
 	 * Defines actions available in a context of elements matching some query.
 	 *
@@ -991,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;