Ability to determine session freshness state

CHANGELOG.md

@@ -6,6 +6,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ### Added
 - Specify failed PHPUnit assertion text to the BrowserStack ("reason" field)/SauceLabs("custom-data" field) test.
 - Added the `$auto_create` parameter to the `BrowserTestCase::getSession` method, which allows to verify is session is already started.
+- Added the `ISessionStrategy::isFreshSession` method to indicate fact, that previous `ISessionStrategy::session` call have created a new session instead of reusing a previously created one. Can be used to perform a login once per a test case class. 
 
 ### Changed
 - Bumped minimum PHP version to 5.6.

docs/configuration.rst

@@ -29,13 +29,13 @@ in that test case class.
 Browser Session Sharing
 ^^^^^^^^^^^^^^^^^^^^^^^
 As a benefit of the shared (per test case) browser configuration, that was described above is an ability
-to not only to share the browser configuration, that is used to create `Mink`_ session, but to actually share
+to not only share the browser configuration, that is used to create `Mink`_ session, but to actually share
 created sessions between all tests in a single test case. This can be done by adding the ``sessionStrategy``
 option (line 15) to the browser configuration.
 
 .. literalinclude:: examples/configuration/per_test_case_browser_config.php
        :linenos:
-       :emphasize-lines: 15
+       :emphasize-lines: 15,26,48
 
 Selecting the Mink Driver
 ^^^^^^^^^^^^^^^^^^^^^^^^^

docs/examples/configuration/per_test_case_browser_config.php

@@ -16,4 +16,42 @@ class CommonBrowserConfigTest extends BrowserTestCase
         ),
     );
 
+    /**
+     * @before
+     */
+    public function setUpTest()
+    {
+        parent::setUpTest();
+
+        if ( $this->getSessionStrategy()->isFreshSession() ) {
+            // login once before any of the tests was started
+        }
+    }
+
+    public function testOne()
+    {
+        // user will be already logged-in regardless
+        // of the test execution order/filtering
+    }
+
+    public function testTwo()
+    {
+        // user will be already logged-in regardless
+        // of the test execution order/filtering
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function onTestSuiteEnded()
+    {
+        $session = $this->getSession(false);
+
+        if ( $session !== null && $session->isStarted() ) {
+            // logout once after all the tests were finished
+        }
+
+        return parent::onTestSuiteEnded();
+    }
+
 }

library/aik099/PHPUnit/Session/AbstractSessionStrategy.php

@@ -0,0 +1,74 @@
+<?php
+/**
+ * This file is part of the phpunit-mink library.
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ *
+ * @copyright Alexander Obuhovich <aik.bold@gmail.com>
+ * @link      https://github.com/aik099/phpunit-mink
+ */
+
+namespace aik099\PHPUnit\Session;
+
+
+use aik099\PHPUnit\BrowserTestCase;
+use Behat\Mink\Session;
+
+abstract class AbstractSessionStrategy implements ISessionStrategy
+{
+
+	/**
+	 * Determines if the session was just started.
+	 *
+	 * @var boolean|null
+	 */
+	protected $isFreshSession;
+
+	/**
+	 * @inheritDoc
+	 */
+	public function isFreshSession()
+	{
+		return $this->isFreshSession;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public function onTestEnded(BrowserTestCase $test_case)
+	{
+
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public function onTestFailed(BrowserTestCase $test_case, $exception)
+	{
+
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public function onTestSuiteEnded(BrowserTestCase $test_case)
+	{
+
+	}
+
+	/**
+	 * Stops the session.
+	 *
+	 * @param Session|null $session Session.
+	 *
+	 * @return void
+	 */
+	protected function stopSession(Session $session = null)
+	{
+		if ( $session !== null && $session->isStarted() ) {
+			$session->stop();
+			$this->isFreshSession = null;
+		}
+	}
+
+}

library/aik099/PHPUnit/Session/ISessionStrategy.php

@@ -32,6 +32,13 @@ interface ISessionStrategy
 	 */
 	public function session(BrowserConfiguration $browser);
 
+	/**
+	 * Determines if the session was just started.
+	 *
+	 * @return boolean|null
+	 */
+	public function isFreshSession();
+
 	/**
 	 * Hook, called from "BrowserTestCase::tearDownTest" method.
 	 *

library/aik099/PHPUnit/Session/IsolatedSessionStrategy.php

@@ -20,7 +20,7 @@
  *
  * @method \Mockery\Expectation shouldReceive(string $name)
  */
-class IsolatedSessionStrategy implements ISessionStrategy
+class IsolatedSessionStrategy extends AbstractSessionStrategy
 {
 
 	/**
@@ -41,15 +41,14 @@ public function __construct(ISessionFactory $session_factory)
 	}
 
 	/**
-	 * Returns Mink session with given browser configuration.
-	 *
-	 * @param BrowserConfiguration $browser Browser configuration for a session.
-	 *
-	 * @return Session
+	 * @inheritDoc
 	 */
 	public function session(BrowserConfiguration $browser)
 	{
-		return $this->_sessionFactory->createSession($browser);
+		$session = $this->_sessionFactory->createSession($browser);
+		$this->isFreshSession = true;
+
+		return $session;
 	}
 
 	/**
@@ -59,25 +58,7 @@ public function onTestEnded(BrowserTestCase $test_case)
 	{
 		$session = $test_case->getSession(false);
 
-		if ( $session !== null && $session->isStarted() ) {
-			$session->stop();
-		}
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	public function onTestFailed(BrowserTestCase $test_case, $exception)
-	{
-
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	public function onTestSuiteEnded(BrowserTestCase $test_case)
-	{
-
+		$this->stopSession($session);
 	}
 
 }

library/aik099/PHPUnit/Session/SharedSessionStrategy.php

@@ -22,7 +22,7 @@
  *
  * @method \Mockery\Expectation shouldReceive(string $name)
  */
-class SharedSessionStrategy implements ISessionStrategy
+class SharedSessionStrategy extends AbstractSessionStrategy
 {
 
 	/**
@@ -57,42 +57,38 @@ public function __construct(ISessionStrategy $original_strategy)
 	}
 
 	/**
-	 * Returns Mink session with given browser configuration.
-	 *
-	 * @param BrowserConfiguration $browser Browser configuration for a session.
-	 *
-	 * @return Session
+	 * @inheritDoc
 	 */
 	public function session(BrowserConfiguration $browser)
 	{
 		if ( $this->_lastTestFailed ) {
-			$this->stopSession();
+			$this->stopAndForgetSession();
 			$this->_lastTestFailed = false;
 		}
 
 		if ( $this->_session === null ) {
 			$this->_session = $this->_originalStrategy->session($browser);
+			$this->isFreshSession = $this->_originalStrategy->isFreshSession();
 		}
 		else {
+			$this->isFreshSession = false;
 			$this->_switchToMainWindow();
 		}
 
 		return $this->_session;
 	}
 
 	/**
-	 * Stops session.
+	 * Stops and forgets a session.
 	 *
 	 * @return void
 	 */
-	protected function stopSession()
+	protected function stopAndForgetSession()
 	{
-		if ( $this->_session === null ) {
-			return;
+		if ( $this->_session !== null ) {
+			$this->stopSession($this->_session);
+			$this->_session = null;
 		}
-
-		$this->_session->stop();
-		$this->_session = null;
 	}
 
 	/**
@@ -105,14 +101,6 @@ private function _switchToMainWindow()
 		$this->_session->switchToWindow(null);
 	}
 
-	/**
-	 * @inheritDoc
-	 */
-	public function onTestEnded(BrowserTestCase $test_case)
-	{
-
-	}
-
 	/**
 	 * @inheritDoc
 	 */
@@ -132,9 +120,7 @@ public function onTestSuiteEnded(BrowserTestCase $test_case)
 	{
 		$session = $test_case->getSession(false);
 
-		if ( $session !== null && $session->isStarted() ) {
-			$session->stop();
-		}
+		$this->stopSession($session);
 	}
 
 }

tests/aik099/PHPUnit/Session/SessionStrategyTestCase.php → tests/aik099/PHPUnit/Session/AbstractSessionStrategyTestCase.php

@@ -17,7 +17,7 @@
 use Behat\Mink\Session;
 use aik099\PHPUnit\BrowserTestCase;
 
-class SessionStrategyTestCase extends AbstractTestCase
+abstract class AbstractSessionStrategyTestCase extends AbstractTestCase
 {
 
 	const BROWSER_CLASS = BrowserConfiguration::class;
@@ -33,4 +33,9 @@ class SessionStrategyTestCase extends AbstractTestCase
 	 */
 	protected $strategy;
 
+	public function testUnknownSessionFreshnessStateUntilItsStarted()
+	{
+		$this->assertNull($this->strategy->isFreshSession());
+	}
+
 }

tests/aik099/PHPUnit/Session/IsolatedSessionStrategyTest.php

@@ -16,7 +16,7 @@
 use Mockery as m;
 use Mockery\MockInterface;
 
-class IsolatedSessionStrategyTest extends SessionStrategyTestCase
+class IsolatedSessionStrategyTest extends AbstractSessionStrategyTestCase
 {
 
 	/**
@@ -57,6 +57,18 @@ public function testSession()
 		$this->assertEquals($session2, $this->strategy->session($browser));
 	}
 
+	public function testIsFreshSessionAfterSessionIsStarted()
+	{
+		$browser = m::mock(self::BROWSER_CLASS);
+		$session = m::mock(self::SESSION_CLASS);
+
+		$this->_factory->shouldReceive('createSession')->with($browser)->once()->andReturn($session);
+
+		$this->strategy->session($browser);
+
+		$this->assertTrue($this->strategy->isFreshSession());
+	}
+
 	/**
 	 * Test description.
 	 *