Repository: nightwatchjs/nightwatch
Pull request #2972 (2021-12-06 16:17:32)

Feat: textEquals assertion
Related issue: https://github.com/nightwatchjs/nightwatch/issues/3002

Thanks in advance for your contribution. Please follow the below steps in submitting a pull request, as it will help us with reviewing it quicker.

- [ ] Create a new branch from master (e.g. `features/my-new-feature` or `issue/123-my-bugfix`);
- [ ] If you're fixing a bug also create an issue if one doesn't exist yet;
- [ ] If it's a new feature explain why do you think it's necessary. Please check with the maintainers beforehand to make sure it is something that we will accept. Usually we only accept new features if we feel that they will benefit the entire community;
- [ ] Please avoid sending PRs which contain drastic or low level changes. If you are certain that the changes are needed, please discuss them beforehand and indicate what the impact will be;
- [ ] If your change is based on existing functionality please consider refactoring first. Pull requests that duplicate code will most likely be ignored;
- [ ] Do not include changes that are not related to the issue at hand;
- [ ] Follow the same coding style with regards to spaces, semicolons, variable naming etc.;
- [ ] Always add unit tests - PRs without tests are most of the times ignored.



Patch:
diff --git a/lib/api/assertions/textEquals.js b/lib/api/assertions/textEquals.js
new file mode 100644
index 00000000..93f4f178
--- /dev/null
+++ b/lib/api/assertions/textEquals.js
@@ -0,0 +1,68 @@
+/**
+ * Check if an elements inner text equals the expected text
+ *
+ * @example
+ * 
+ * ```
+ *   this.demoTest = function (browser) {
+ *     browser.assert.textEquals('#main', 'The Night Watch');
+ *   };
+ * ```
+ * 
+ * @method textEquals 
+ * @param {string|object} definition The selector (CSS/Xpath) used to locate the element. Can either be a string or an object which specifies [element properties](https://nightwatchjs.org/guide#element-properties).
+ * @param {string} expected text to match text.
+ * @param {string} [msg] Optional log message to display in the output. If missing, one is displayed by default.
+ * @api assertions
+ */
+
+const {setElementSelectorProps} = require('../../utils');
+
+exports.assertion = function(definition, expected, msg) {
+  this.options = {
+    elementSelector: true
+  };
+ 
+  this.formatMessage = function() {
+    const message = msg || `Testing if element %s ${this.negate ? 'doesn\'t equal %s' : 'equals %s'}`;
+ 
+    return {
+      message,
+      args: [this.elementSelector, `'${expected}'`]
+    };
+  };
+ 
+  this.expected = function() {
+    return this.negate ? `doesn't equal '${expected}'` : `equals '${expected}'`;
+  };
+ 
+  this.evaluate = function(value) {
+    if (typeof value != 'string') {
+      return false;
+    }
+
+    return value === expected;
+  };
+
+  this.failure = function(result) {
+    return result === false || result && result.status === -1;
+  };
+  
+  this.value = function(result) {
+    if (result.status === -1) {
+      return null;
+    }
+
+    return result.value;
+  };
+
+  this.actual = function(passed) {
+    return passed ? `equals '${expected}'` : `doesn't equal '${expected}'`;
+  };
+ 
+  this.command = function(callback) {
+    this.api.getText(setElementSelectorProps(definition, {
+      suppressNotFoundErrors: true
+    }), callback);
+  };
+};
\ No newline at end of file


Test patch:
diff --git a/test/src/api/assertions/testTextEquals.js b/test/src/api/assertions/testTextEquals.js
new file mode 100644
index 00000000..d9513f2c
--- /dev/null
+++ b/test/src/api/assertions/testTextEquals.js
@@ -0,0 +1,119 @@
+const assert = require('assert');
+const Globals = require('../../../lib/globals.js');
+
+describe('assert.textEquals', function () {
+  const assertionName = 'textEquals';
+  const api = 'getText';
+
+  function assertionTest(opts) {
+    return Globals.assertion(assertionName, api, opts);
+  }
+
+  it('textEquals assertion passed', function () {
+    return assertionTest({
+      args: ['.test_element', 'text result', 'Test message'],
+      commandResult: {
+        value: 'text result'
+      },
+      assertArgs: true,
+      assertMessage: true,
+      assertion({reporter, instance, failure}) {
+        assert.deepStrictEqual(instance.options, {elementSelector: true});
+        assert.strictEqual(failure, false);
+        assert.strictEqual(instance.getValue(), 'text result');
+        assert.strictEqual(instance.hasFailure(), false);
+      }
+    });
+  });
+
+  it('not.textEquals assertion passed', function () {
+    return assertionTest({
+      args: ['.test_element', 'text result', 'Test message'],
+      commandResult: {
+        value: 'other text'
+      },
+      negate: true,
+      assertion({reporter, instance, queueOpts, message}) {
+        assert.strictEqual(typeof err, 'undefined');
+        assert.strictEqual(queueOpts.negate, true);
+
+        assert.strictEqual(instance.hasFailure(), false);
+        assert.strictEqual(instance.getValue(), 'other text');
+        assert.strictEqual(instance.getActual(), 'doesn\'t equal \'text result\'');
+        assert.strictEqual(instance.message, 'Test message');
+      }
+    });
+  });
+
+  it('not.textEquals assertion failed', function () {
+    return assertionTest({
+      args: ['.test_element', 'text result', 'Test message'],
+      commandResult: {
+        value: 'text result'
+      },
+      negate: true,
+      assertError: true,
+      assertion({instance, queueOpts, err}) {
+        assert.strictEqual(queueOpts.negate, true);
+        assert.strictEqual(instance.hasFailure(), false);
+        assert.strictEqual(instance.getValue(), 'text result');
+        assert.strictEqual(instance.getActual(), 'equals \'text result\'');
+        assert.strictEqual(err.message, `Test message in 5ms - expected "doesn't equal 'text result'" but got: "equals 'text result'" (${instance.elapsedTime}ms)`);
+      }
+    });
+  });
+
+  it('textEquals assertion passed with selector object', function () {
+    return assertionTest({
+      args: [{selector: '.test_element'}, 'text result'],
+      commandResult: {
+        value: 'text result'
+      },
+      assertArgs: true,
+      assertResult: true,
+      assertion({instance, failure, message, err}) {
+        assert.ok(message.startsWith('Testing if element <.test_element> equals \'text result\''), message);
+        assert.deepStrictEqual(instance.options, {elementSelector: true});
+        assert.strictEqual(instance.getActual(), 'equals \'text result\'');
+        assert.strictEqual(instance.hasFailure(), false);
+        assert.ok(message.startsWith('Testing if element <.test_element> equals \'text result\''), message);
+        assert.strictEqual(failure, false);
+      }
+    });
+  });
+
+  it('textEquals assertion failed', function () {
+    return assertionTest({
+      args: ['.test_element', 'text result', 'Test message'],
+      commandResult: {
+        value: 'not_expected'
+      },
+      assertError: true,
+      assertResult: true,
+      assertion({instance, failure}) {
+        assert.strictEqual(instance.getActual(), 'doesn\'t equal \'text result\'');
+        assert.strictEqual(failure, 'Expected "equals \'text result\'" but got: "doesn\'t equal \'text result\'"');
+      }
+    });
+  });
+
+  it('textEquals assertion - element not found', function () {
+    return assertionTest({
+      args: ['.test_element', 'text result', 'Test message'],
+      commandResult: {
+        status: -1
+      },
+      assertError: true,
+      assertFailure: true,
+      assertResult: true,
+      assertion({instance, failure, err}) {
+        assert.strictEqual(instance.getActual(), 'element could not be located');
+        assert.strictEqual(instance.expected(), 'equals \'text result\'');
+        assert.strictEqual(instance.getValue(), null);
+        assert.strictEqual(failure, 'Expected "equals \'text result\'" but got: "element could not be located"');
+        assert.strictEqual(err.message, `Test message in 5ms - expected "equals 'text result'" but got: "element could not be located" (${instance.elapsedTime}ms)`);
+      }
+    });
+  });
+});
+