From 1e6c7b471ef35344d5b0f52dc5a3942c48f2bef3 Mon Sep 17 00:00:00 2001
From: Shawn McCabe <smccabe@acromediainc.com>
Date: Thu, 2 Dec 2021 14:39:08 -0800
Subject: [PATCH] Add waitFor return check since waitForText doesn't assert

---
 .../Sniffs/FunctionCalls/WaitForTextSniff.php | 83 +++++++++++++++++++
 .../FunctionCalls/WaitForTextUnitTest.inc     | 15 ++++
 .../FunctionCalls/WaitForTextUnitTest.php     | 57 +++++++++++++
 3 files changed, 155 insertions(+)
 create mode 100644 coder_sniffer/DrupalPractice/Sniffs/FunctionCalls/WaitForTextSniff.php
 create mode 100644 tests/DrupalPractice/FunctionCalls/WaitForTextUnitTest.inc
 create mode 100644 tests/DrupalPractice/FunctionCalls/WaitForTextUnitTest.php

diff --git a/coder_sniffer/DrupalPractice/Sniffs/FunctionCalls/WaitForTextSniff.php b/coder_sniffer/DrupalPractice/Sniffs/FunctionCalls/WaitForTextSniff.php
new file mode 100644
index 00000000..7af46be8
--- /dev/null
+++ b/coder_sniffer/DrupalPractice/Sniffs/FunctionCalls/WaitForTextSniff.php
@@ -0,0 +1,83 @@
+<?php
+/**
+ * \DrupalPractice\Sniffs\FunctionCalls\WaitForText
+ *
+ * @category PHP
+ * @package  PHP_CodeSniffer
+ * @link     http://pear.php.net/package/PHP_CodeSniffer
+ */
+
+namespace DrupalPractice\Sniffs\FunctionCalls;
+
+use PHP_CodeSniffer\Files\File;
+use Drupal\Sniffs\Semantics\FunctionCall;
+
+/**
+ * Check that waitForText return values are always handled.
+ *
+ * @category PHP
+ * @package  PHP_CodeSniffer
+ * @link     http://pear.php.net/package/PHP_CodeSniffer
+ */
+class WaitForTextSniff extends FunctionCall
+{
+    /**
+     * Whether method invocations with the same function name should be processed,
+     * too.
+     *
+     * @var boolean
+     */
+    protected $includeMethodCalls = true;
+
+
+    /**
+     * Returns an array of function names this test wants to listen for.
+     *
+     * @return array<string>
+     */
+    public function registerFunctionNames()
+    {
+        return ['waitForText'];
+
+    }//end registerFunctionNames()
+
+
+    /**
+     * Processes this function call.
+     *
+     * @param \PHP_CodeSniffer\Files\File $phpcsFile    The file being scanned.
+     * @param int                         $stackPtr     The position of the function call in
+     *                                                  the stack.
+     * @param int                         $openBracket  The position of the opening
+     *                                                  parenthesis in the stack.
+     * @param int                         $closeBracket The position of the closing
+     *                                                  parenthesis in the stack.
+     *
+     * @return void|int
+     */
+    public function processFunctionCall(
+        File $phpcsFile,
+        $stackPtr,
+        $openBracket,
+        $closeBracket
+    ) {
+        $tokens = $phpcsFile->getTokens();
+
+        $start = $phpcsFile->findStartOfStatement($stackPtr);
+        $end   = $phpcsFile->findEndOfStatement($start);
+        // We are assigning to a variable, all is well.
+        if ($tokens[$start]['code'] === T_VARIABLE && $phpcsFile->findNext(T_EQUAL, $start, $end) !== false) {
+            return;
+        }
+
+        $function = ($start - 2);
+        if ($tokens[$function]['content'] === 'assertTrue' || $tokens[$function]['content'] === 'assertFalse') {
+            return;
+        }
+
+        $phpcsFile->addWarning('waitForText functions do not self assert and must be asserted manually', $start, 'WaitForText');
+
+    }//end processFunctionCall()
+
+
+}//end class
diff --git a/tests/DrupalPractice/FunctionCalls/WaitForTextUnitTest.inc b/tests/DrupalPractice/FunctionCalls/WaitForTextUnitTest.inc
new file mode 100644
index 00000000..34771d92
--- /dev/null
+++ b/tests/DrupalPractice/FunctionCalls/WaitForTextUnitTest.inc
@@ -0,0 +1,15 @@
+<?php
+
+// Correct assertion
+$this->assertTrue($this->assertSession()->waitForText('Example Text'));
+$this->assertFalse($this->assertSession()->waitForText('Example Text'));
+
+// Assigned to a variable which we assume will be asserted later
+$wait = $this->assertSession()->waitForText('Example Text');
+
+// Incorrect assertion, waitForText only returns true or false and should be asserted as such
+$this->assertEmpty($this->assertSession()->waitForText('Example Text'));
+
+// No Assertion, failure
+$this->assertSession()->waitForText('Example Text');
+
diff --git a/tests/DrupalPractice/FunctionCalls/WaitForTextUnitTest.php b/tests/DrupalPractice/FunctionCalls/WaitForTextUnitTest.php
new file mode 100644
index 00000000..f8e3428d
--- /dev/null
+++ b/tests/DrupalPractice/FunctionCalls/WaitForTextUnitTest.php
@@ -0,0 +1,57 @@
+<?php
+/**
+ * Unit test class for the DbQuery sniff.
+ */
+
+namespace DrupalPractice\Test\FunctionCalls;
+
+use Drupal\Test\CoderSniffUnitTest;
+
+/**
+ * Unit test class for the WaitForText sniff.
+ *
+ * A sniff unit test checks a .inc file for expected violations of a single
+ * coding standard. Expected errors and warnings are stored in this class.
+ */
+class WaitForTextUnitTest extends CoderSniffUnitTest
+{
+
+
+    /**
+     * Returns the lines where errors should occur.
+     *
+     * The key of the array should represent the line number and the value
+     * should represent the number of errors that should occur on that line.
+     *
+     * @param string $testFile The name of the file being tested.
+     *
+     * @return array<int, int>
+     */
+    protected function getErrorList(string $testFile): array
+    {
+        return [];
+
+    }//end getErrorList()
+
+
+    /**
+     * Returns the lines where warnings should occur.
+     *
+     * The key of the array should represent the line number and the value
+     * should represent the number of warnings that should occur on that line.
+     *
+     * @param string $testFile The name of the file being tested.
+     *
+     * @return array<int, int>
+     */
+    protected function getWarningList(string $testFile): array
+    {
+        return [
+            11 => 1,
+            14 => 1,
+        ];
+
+    }//end getWarningList()
+
+
+}//end class