ngx-speculoos 6.0.0 → 7.2.0

package/{fesm2015/ngx-speculoos.js → fesm2020/ngx-speculoos.mjs}

@@ -1,7 +1,7 @@
 import { ComponentFixture, TestBed } from '@angular/core/testing';
 import { By } from '@angular/platform-browser';
-import { convertToParamMap } from '@angular/router';
-import { map } from 'rxjs/operators';
+import { convertToParamMap, ActivatedRouteSnapshot, ActivatedRoute } from '@angular/router';
+import { map, BehaviorSubject } from 'rxjs';
 
 /**
  * A wrapped DOM element, providing additional methods and attributes helping with writing tests
@@ -60,7 +60,7 @@ class TestElement {
     }
     /**
      * Gets the first input matched by the given selector. Throws an Error if the matched element isn't actually an input.
-     * @param selector a CSS selector
+     * @param selector a CSS or directive selector
      * @returns the wrapped input, or null if no element was matched
      */
     input(selector) {
@@ -68,7 +68,7 @@ class TestElement {
     }
     /**
      * Gets the first select matched by the given selector. Throws an Error if the matched element isn't actually a select.
-     * @param selector a CSS selector
+     * @param selector a CSS or directive selector
      * @returns the wrapped select, or null if no element was matched
      */
     select(selector) {
@@ -76,7 +76,7 @@ class TestElement {
     }
     /**
      * Gets the first textarea matched by the given selector
-     * @param selector a CSS selector
+     * @param selector a CSS or directive selector
      * @returns the wrapped textarea, or null if no element was matched. Throws an Error if the matched element isn't actually a textarea.
      * @throws {Error} if the matched element isn't actually a textarea
      */
@@ -85,12 +85,63 @@ class TestElement {
     }
     /**
      * Gets the first button matched by the given selector. Throws an Error if the matched element isn't actually a button.
-     * @param selector a CSS selector
+     * @param selector a CSS or directive selector
      * @returns the wrapped button, or null if no element was matched
      */
     button(selector) {
         return this.querier.button(selector);
     }
+    /**
+     * Gets the first directive matching the given component directive selector and returns its component instance
+     * @param selector the selector of a component directive
+     */
+    component(selector) {
+        return this.querier.element(selector)?.debugElement?.componentInstance ?? null;
+    }
+    /**
+     * Gets the directives matching the given component directive selector and returns their component instance
+     * @param selector the selector of a component directive
+     */
+    components(selector) {
+        return this.querier.elements(selector).map(e => e.debugElement.componentInstance);
+    }
+    /**
+     * Gets the first element matching the given selector, then gets the given token from its injector, or null if there is no such token
+     * @param selector a CSS or directive selector
+     * @param token the token to get from the matched element injector
+     */
+    token(selector, token) {
+        return this.querier.element(selector)?.debugElement?.injector?.get(token, null) ?? null;
+    }
+    /**
+     * Gets the elements matching the given selector, then gets their given token from their injector, or null if there is no such token
+     * @param selector a CSS or directive selector
+     * @param token the token to get from the matched element injector
+     */
+    tokens(selector, token) {
+        return this.querier.elements(selector).map(e => e.debugElement.injector.get(token, null) ?? null);
+    }
+    /**
+     * Gets the element matching the given selector, and if found, creates and returns a custom TestElement of the provided
+     * type. This is useful to create custom higher-level abstractions similar to TestInput, TestSelect, etc. for
+     * custom elements or components.
+     * @param selector a CSS or directive selector
+     * @param customTestElementType the type of the TestElement subclass that will wrap the found element
+     */
+    custom(selector, customTestElementType) {
+        const element = this.querier.element(selector);
+        return element && new customTestElementType(this.tester, element.debugElement);
+    }
+    /**
+     * Gets the elements matching the given selector, and creates and returns custom TestElements of the provided
+     * type. This is useful to create custom higher-level abstractions similar to TestInput, TestSelect, etc. for
+     * custom elements or components.
+     * @param selector a CSS or directive selector
+     * @param customTestElementType the type of the TestElement subclass that will wrap the found elements
+     */
+    customs(selector, customTestElementType) {
+        return this.querier.elements(selector).map(element => new customTestElementType(this.tester, element.debugElement));
+    }
 }
 
 /**
@@ -296,6 +347,7 @@ class TestInput extends TestHtmlElement {
     }
 }
 
+/* eslint-disable @typescript-eslint/no-explicit-any */
 /**
  * @internal
  */
@@ -326,11 +378,11 @@ class TestElementQuerier {
         }
     }
     /**
-     * Gets the first element matching the given CSS selector and wraps it into a TestElement. The actual type
+     * Gets the first element matching the given selector and wraps it into a TestElement. The actual type
      * of the returned value is the TestElement subclass matching the type of the found element. So, if the
      * matched element is an input for example, the method will return a TestInput. You can thus use
      * `tester.element('#some-input') as TestInput`.
-     * @param selector a CSS selector
+     * @param selector a CSS or directive selector
      * @returns the wrapped element, or null if no element matches the selector.
      */
     element(selector) {
@@ -338,11 +390,11 @@ class TestElementQuerier {
         return childElement && TestElementQuerier.wrap(childElement, this.tester);
     }
     /**
-     * Gets all the elements matching the given CSS selector and wraps them into a TestElement. The actual type
+     * Gets all the elements matching the given selector and wraps them into a TestElement. The actual type
      * of the returned elements is the TestElement subclass matching the type of the found element. So, if the
      * matched elements are inputs for example, the method will return an array of TestInput. You can thus use
      * `tester.elements('input') as Array<TestInput>`.
-     * @param selector a CSS selector
+     * @param selector a CSS or directive selector
      * @returns the array of matched elements, empty if no element was matched
      */
     elements(selector) {
@@ -351,7 +403,7 @@ class TestElementQuerier {
     }
     /**
      * Gets the first input matched by the given selector. Throws an Error if the matched element isn't actually an input.
-     * @param selector a CSS selector
+     * @param selector a CSS or directive selector
      * @returns the wrapped input, or null if no element was matched
      */
     input(selector) {
@@ -366,7 +418,7 @@ class TestElementQuerier {
     }
     /**
      * Gets the first select matched by the given selector. Throws an Error if the matched element isn't actually a select.
-     * @param selector a CSS selector
+     * @param selector a CSS or directive selector
      * @returns the wrapped select, or null if no element was matched
      */
     select(selector) {
@@ -381,7 +433,7 @@ class TestElementQuerier {
     }
     /**
      * Gets the first textarea matched by the given selector
-     * @param selector a CSS selector
+     * @param selector a CSS or directive selector
      * @returns the wrapped textarea, or null if no element was matched. Throws an Error if the matched element isn't actually a textarea.
      * @throws {Error} if the matched element isn't actually a textarea
      */
@@ -397,7 +449,7 @@ class TestElementQuerier {
     }
     /**
      * Gets the first button matched by the given selector. Throws an Error if the matched element isn't actually a button.
-     * @param selector a CSS selector
+     * @param selector a CSS or directive selector
      * @returns the wrapped button, or null if no element was matched
      */
     button(selector) {
@@ -411,10 +463,20 @@ class TestElementQuerier {
         return new TestButton(this.tester, childElement);
     }
     query(selector) {
-        return this.root.query(By.css(selector));
+        if (typeof selector === 'string') {
+            return this.root.query(By.css(selector));
+        }
+        else {
+            return this.root.query(By.directive(selector));
+        }
     }
     queryAll(selector) {
-        return this.root.queryAll(By.css(selector));
+        if (typeof selector === 'string') {
+            return this.root.queryAll(By.css(selector));
+        }
+        else {
+            return this.root.queryAll(By.directive(selector));
+        }
     }
 }
 
@@ -473,7 +535,7 @@ class ComponentTester {
     }
     /**
      * Gets the first input matched by the given selector. Throws an Error if the matched element isn't actually an input.
-     * @param selector a CSS selector
+     * @param selector a CSS or directive selector
      * @returns the wrapped input, or null if no element was matched
      */
     input(selector) {
@@ -481,7 +543,7 @@ class ComponentTester {
     }
     /**
      * Gets the first select matched by the given selector. Throws an Error if the matched element isn't actually a select.
-     * @param selector a CSS selector
+     * @param selector a CSS or directive selector
      * @returns the wrapped select, or null if no element was matched
      */
     select(selector) {
@@ -489,7 +551,7 @@ class ComponentTester {
     }
     /**
      * Gets the first textarea matched by the given selector
-     * @param selector a CSS selector
+     * @param selector a CSS or directive selector
      * @returns the wrapped textarea, or null if no element was matched. Throws an Error if the matched element isn't actually a textarea.
      * @throws {Error} if the matched element isn't actually a textarea
      */
@@ -498,12 +560,62 @@ class ComponentTester {
     }
     /**
      * Gets the first button matched by the given selector. Throws an Error if the matched element isn't actually a button.
-     * @param selector a CSS selector
+     * @param selector a CSS or directive selector
      * @returns the wrapped button, or null if no element was matched
      */
     button(selector) {
         return this.testElement.button(selector);
     }
+    /**
+     * Gets the first directive matching the given component directive selector and returns its component instance
+     * @param selector the selector of a component directive
+     */
+    component(selector) {
+        return this.testElement.component(selector);
+    }
+    /**
+     * Gets the directives matching the given component directive selector and returns their component instance
+     * @param selector the selector of a component directive
+     */
+    components(selector) {
+        return this.testElement.components(selector);
+    }
+    /**
+     * Gets the first element matching the given selector, then gets the given token from its injector, or null if there is no such token
+     * @param selector a CSS or directive selector
+     * @param token the token to get from the matched element injector
+     */
+    token(selector, token) {
+        return this.testElement.token(selector, token);
+    }
+    /**
+     * Gets the elements matching the given selector, then gets their given token from their injector, or null if there is no such token
+     * @param selector a CSS or directive selector
+     * @param token the token to get from the matched element injector
+     */
+    tokens(selector, token) {
+        return this.testElement.tokens(selector, token);
+    }
+    /**
+     * Gets the element matching the given selector, and if found, creates and returns a custom TestElement of the provided
+     * type. This is useful to create custom higher-level abstractions similar to TestInput, TestSelect, etc. for
+     * custom elements or components.
+     * @param selector a CSS or directive selector
+     * @param customTestElementType the type of the TestElement subclass that will wrap the found element
+     */
+    custom(selector, customTestElementType) {
+        return this.testElement.custom(selector, customTestElementType);
+    }
+    /**
+     * Gets the elements matching the given selector, and creates and returns custom TestElements of the provided
+     * type. This is useful to create custom higher-level abstractions similar to TestInput, TestSelect, etc. for
+     * custom elements or components.
+     * @param selector a CSS or directive selector
+     * @param customTestElementType the type of the TestElement subclass that will wrap the found elements
+     */
+    customs(selector, customTestElementType) {
+        return this.testElement.customs(selector, customTestElementType);
+    }
     /**
      * Triggers a change detection using the wrapped fixture
      */
@@ -527,6 +639,7 @@ class ComponentTester {
  * `route.parent.snapshot` or `route.snapshot.parent`.
  *
  * @returns a partially populated, fake ActivatedRoute, depending on what you passed in
+ * @deprecated favor stubRoute, which creates an easier to use and more logical stub
  */
 function fakeRoute(options) {
     const result = {
@@ -549,12 +662,14 @@ function fakeRoute(options) {
     };
     for (let route = result; route; route = route.parent) {
         if (route.parent && route.parent.snapshot && !route.snapshot) {
+            // eslint-disable-next-line deprecation/deprecation
             route.snapshot = fakeSnapshot({});
         }
         if (route.parent && route.parent.snapshot && !route.snapshot.parent) {
             route.snapshot.parent = route.parent.snapshot;
         }
         if (route.snapshot && route.snapshot.parent && !route.parent) {
+            // eslint-disable-next-line deprecation/deprecation
             route.parent = fakeRoute({});
         }
         if (route.snapshot && route.snapshot.parent && route.parent && !route.parent.snapshot) {
@@ -570,6 +685,7 @@ function fakeRoute(options) {
  * The same goes for queryParams and queryParamMap.
  *
  * @returns a partially populated, fake ActivatedRoute, depending on what you passed in
+ * @deprecated favor stubRoute, which creates an easier to use and more logical stub for both the route and its snapshot
  */
 function fakeSnapshot(options) {
     return {
@@ -590,6 +706,240 @@ function fakeSnapshot(options) {
         pathFromRoot: options.pathFromRoot
     };
 }
+class ActivatedRouteSnapshotStub extends ActivatedRouteSnapshot {
+    constructor() {
+        super();
+        this._parent = null;
+        this._firstChild = null;
+        this._children = [];
+        this._pathFromRoot = [];
+        this._routeConfig = null;
+        this._root = this;
+    }
+    get parent() {
+        return this._parent;
+    }
+    set parent(value) {
+        this._parent = value;
+    }
+    get root() {
+        return this._root;
+    }
+    set root(value) {
+        this._root = value;
+    }
+    get firstChild() {
+        return this._firstChild;
+    }
+    set firstChild(value) {
+        this._firstChild = value;
+    }
+    get children() {
+        return this._children;
+    }
+    set children(value) {
+        this._children = value;
+    }
+    get pathFromRoot() {
+        return this._pathFromRoot;
+    }
+    set pathFromRoot(value) {
+        this._pathFromRoot = value;
+    }
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    get routeConfig() {
+        return this._routeConfig;
+    }
+    set routeConfig(route) {
+        this._routeConfig = route;
+    }
+}
+/**
+ * A stub for ActivatedRoute. It behaves almost the same way as the actual ActivatedRoute, exposing a snapshot
+ * and observables for the params, query params etc., which are kept in sync.
+ *
+ * In addition, this stub allows simulating a navigation by changing the params, the query params, the fragment, etc.
+ * When that happens, the snapshot is modified, then the relevant observables emit the new values.
+ *
+ * There are some things that don't really work the same way as the real ActivatedRoute though:
+ * - the handling of the firstChild and of the children is entirely under the tester's responsibility. Setting the parent
+ *   of a route stub does not add this route to the children of its parent, for example.
+ * - when changing the params, query params, fragment, etc., their associated observable emits unconditionally, instead of
+ *   first checking if the value is actually different from before. It's thus the responsibility of the tester to not
+ *   change the values if they're the same as before.
+ */
+class ActivatedRouteStub extends ActivatedRoute {
+    /**
+     * Constructs a new instance, based on the given options.
+     * If an option is not provided (or if no option is provided at all), then the route has a default value for this option
+     * (empty parameters for example, null fragment, etc.)
+     * If no parent is passed, then this route has no parent and is thus set as the root. Otherwise, the root and the path
+     * from root are created based on the root and path from root of the given parent route.
+     */
+    constructor(options) {
+        super();
+        const snapshot = new ActivatedRouteSnapshotStub();
+        this.snapshot = snapshot;
+        this._firstChild = options?.firstChild ?? null;
+        this._children = options?.children ?? [];
+        this._parent = options?.parent ?? null;
+        this._root = this.parent?.root ?? this;
+        this._pathFromRoot = this.parent ? [...this.parent.pathFromRoot, this] : [this];
+        snapshot.params = options?.params ?? {};
+        snapshot.queryParams = options?.queryParams ?? {};
+        snapshot.data = options?.data ?? {};
+        snapshot.fragment = options?.fragment ?? null;
+        snapshot.url = options?.url ?? [];
+        snapshot.routeConfig = options?.routeConfig ?? null;
+        snapshot.firstChild = this.firstChild?.snapshot ?? null;
+        snapshot.children = this.children?.map(route => route.snapshot) ?? [];
+        snapshot.parent = this.parent?.snapshot ?? null;
+        snapshot.root = this.root.snapshot;
+        snapshot.pathFromRoot = this.pathFromRoot.map(route => route.snapshot);
+        this.paramsSubject = new BehaviorSubject(this.snapshot.params);
+        this.queryParamsSubject = new BehaviorSubject(this.snapshot.queryParams);
+        this.dataSubject = new BehaviorSubject(this.snapshot.data);
+        this.fragmentSubject = new BehaviorSubject(this.snapshot.fragment);
+        this.urlSubject = new BehaviorSubject(this.snapshot.url);
+        this.params = this.paramsSubject.asObservable();
+        this.queryParams = this.queryParamsSubject.asObservable();
+        this.data = this.dataSubject.asObservable();
+        this.fragment = this.fragmentSubject.asObservable();
+        this.url = this.urlSubject.asObservable();
+    }
+    get root() {
+        return this._root;
+    }
+    get parent() {
+        return this._parent;
+    }
+    get pathFromRoot() {
+        return this._pathFromRoot;
+    }
+    get firstChild() {
+        return this._firstChild;
+    }
+    get children() {
+        return this._children;
+    }
+    get routeConfig() {
+        return this.snapshot.routeConfig;
+    }
+    /**
+     * Triggers a navigation with the given new parameters. All the other parts (query params etc.) stay as the are.
+     * This is a shortcut to `triggerNavigation` that can be used to only change the parameters.
+     */
+    setParams(params) {
+        this.triggerNavigation({ params });
+    }
+    /**
+     * Triggers a navigation with the given new parameter. The other parameters, as well as all the other parts (query params etc.)
+     * stay as the are.
+     * This is a shortcut to `triggerNavigation` that can be used to only change one parameter.
+     */
+    setParam(name, value) {
+        this.setParams({ ...this.snapshot.params, [name]: value });
+    }
+    /**
+     * Triggers a navigation with the given new query parameters. All the other parts (params etc.) stay as the are.
+     * This is a shortcut to `triggerNavigation` that can be used to only change the query parameters.
+     */
+    setQueryParams(queryParams) {
+        this.triggerNavigation({ queryParams });
+    }
+    /**
+     * Triggers a navigation with the given new parameter. The other query parameters, as well as all the other parts (params etc.)
+     * stay as the are.
+     * This is a shortcut to `triggerNavigation` that can be used to only change one query parameter.
+     */
+    setQueryParam(name, value) {
+        this.setQueryParams({ ...this.snapshot.queryParams, [name]: value });
+    }
+    /**
+     * Triggers a navigation with the given new data. The other parameters, as well as all the other parts (params etc.)
+     * stay as the are.
+     * This is a shortcut to `triggerNavigation` that can be used to only change the data.
+     */
+    setData(data) {
+        this.triggerNavigation({ data });
+    }
+    /**
+     * Triggers a navigation with the given new data item. The other data, as well as all the other parts (params etc.)
+     * stay as the are.
+     * This is a shortcut to `triggerNavigation` that can be used to only change one data item.
+     */
+    setDataItem(name, value) {
+        this.setData({ ...this.snapshot.data, [name]: value });
+    }
+    /**
+     * Triggers a navigation with the given new fragment. The other parts (params etc.)  stay as the are.
+     * This is a shortcut to `triggerNavigation` that can be used to only change the fragment.
+     */
+    setFragment(fragment) {
+        this.triggerNavigation({ fragment });
+    }
+    /**
+     * Triggers a navigation with the given new url. The other parts (params etc.)  stay as the are.
+     * This is a shortcut to `triggerNavigation` that can be used to only change the url.
+     */
+    setUrl(url) {
+        this.triggerNavigation({ url });
+    }
+    /**
+     * Triggers a navigation based on the given options. If an option is undefined or null, it's ignored. Except for fragment, which is only
+     * ignored if it's undefined, because null is a valid value for a fragment.
+     *
+     * The non-ignored values are used to change the snapshot of the route. Once the snapshot has been modified,
+     * the observables corresponding to the updated parts emit the new value.
+     *
+     * So, setting params and query params will make the params and queryParams observables emit, but not the fragment, data and
+     * url observables for example. This is consistent to how the router behaves.
+     */
+    triggerNavigation(options) {
+        // set the snapshot first
+        if (options.params) {
+            this.snapshot.params = options.params;
+        }
+        if (options.queryParams) {
+            this.snapshot.queryParams = options.queryParams;
+        }
+        if (options.fragment !== undefined) {
+            this.snapshot.fragment = options.fragment;
+        }
+        if (options.data) {
+            this.snapshot.data = options.data;
+        }
+        if (options.url) {
+            this.snapshot.url = options.url;
+        }
+        // then emit everything that has changed
+        if (options.params) {
+            this.paramsSubject.next(this.snapshot.params);
+        }
+        if (options.queryParams) {
+            this.queryParamsSubject.next(this.snapshot.queryParams);
+        }
+        if (options.fragment !== undefined) {
+            this.fragmentSubject.next(this.snapshot.fragment);
+        }
+        if (options.data) {
+            this.dataSubject.next(this.snapshot.data);
+        }
+        if (options.url) {
+            this.urlSubject.next(this.snapshot.url);
+        }
+    }
+    toString() {
+        return 'ActivatedRouteStub';
+    }
+}
+/**
+ * Creates a new ActivatedRouteStub, by calling its constructor.
+ */
+function stubRoute(options) {
+    return new ActivatedRouteStub(options);
+}
 
 const speculoosMatchers = {
     /**
@@ -671,6 +1021,45 @@ const speculoosMatchers = {
             }
         };
     },
+    /**
+     * Checks that the receiver is a TestElement wrapping a DOM element and has the given textContent, after both have been trimmed.
+     * So, An element such as
+     * ```
+     * <h1>
+     *   Some title
+     * </h1>
+     * ```
+     * will pass the test
+     * ```
+     * expect(tester.title).toHaveTrimmedText('Some title')
+     * ```
+     */
+    toHaveTrimmedText: () => {
+        const assert = (isNegative, el, expected) => {
+            const trimmedExpected = expected.trim();
+            if (!el) {
+                return { pass: false, message: `Expected to check trimmed text '${trimmedExpected}' on element, but element was falsy` };
+            }
+            if (!(el instanceof TestElement)) {
+                return {
+                    pass: false,
+                    message: `Expected to check trimmed text '${trimmedExpected}' on element, but element was not a TestElement`
+                };
+            }
+            const actual = el.textContent?.trim();
+            const pass = actual === trimmedExpected;
+            const message = `Expected element to ${isNegative ? 'not ' : ''}have trimmed text '${trimmedExpected}', but had '${actual}'`;
+            return { pass: isNegative ? !pass : pass, message };
+        };
+        return {
+            compare: (el, expected) => {
+                return assert(false, el, expected);
+            },
+            negativeCompare: (el, expected) => {
+                return assert(true, el, expected);
+            }
+        };
+    },
     /**
      * Checks that the receiver is a TestElement wrapping a DOM element and contains the given textContent
      */
@@ -829,11 +1218,36 @@ const speculoosMatchers = {
     }
 };
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function collectMethodNames(proto) {
+    if (!proto || proto === Object.prototype) {
+        return [];
+    }
+    const methodNames = [];
+    for (const key of Object.getOwnPropertyNames(proto)) {
+        const descriptor = Object.getOwnPropertyDescriptor(proto, key);
+        if (descriptor && typeof descriptor.value === 'function' && key !== 'constructor') {
+            methodNames.push(key);
+        }
+    }
+    return [...methodNames, ...collectMethodNames(Object.getPrototypeOf(proto))];
+}
+/**
+ * Creates a spy object for a class where all the methods of the class (and of its superclasses) are spies.
+ * I.e., for a class `UserService` with methods `get()`, `create()`, `update()` and `delete()`, calling
+ * `createMock(UserService)` is equivalent to calling
+ * `jasmine.createSpyObj<UserService>('UserService', ['get', 'create', 'update', 'delete'])`.
+ * @param type the type to mock (usually a service class)
+ */
+function createMock(type) {
+    return jasmine.createSpyObj(type.name, collectMethodNames(type.prototype));
+}
+
 /* eslint-disable */
 
 /**
  * Generated bundle index. Do not edit.
  */
 
-export { ComponentTester, TestButton, TestElement, TestHtmlElement, TestInput, TestSelect, TestTextArea, fakeRoute, fakeSnapshot, speculoosMatchers };
-//# sourceMappingURL=ngx-speculoos.js.map
+export { ActivatedRouteStub, ComponentTester, TestButton, TestElement, TestHtmlElement, TestInput, TestSelect, TestTextArea, createMock, fakeRoute, fakeSnapshot, speculoosMatchers, stubRoute };
+//# sourceMappingURL=ngx-speculoos.mjs.map