#73 - test documentation

docs/elements/common.html

@@ -0,0 +1,49 @@
+<article-header>Common</article-header>
+
+<article-paragraphs>
+    <p>
+       Add <br>
+        <code class="text-sky-600">Blumilk\BLT\Features\Traits\Common</code> trait to use ready complex functions from Common.
+    </p>
+</article-paragraphs>
+
+<section-header>Authentication Checks and Operations</section-header>
+<article-paragraphs>
+    <p>
+        The <code>Common</code> trait provides several methods to manage and verify authentication states for
+        various objects within your Laravel application. These methods ensure that your application's authentication
+        features are functioning as expected.
+    </p>
+</article-paragraphs>
+
+<article-paragraphs>
+    <p>
+        This snippet authenticates a user by a specified value in a given field and logs them into the session.
+    </p>
+</article-paragraphs>
+<code-snippet
+        gherkin="Given user is authenticated in session as '[email protected]' in email field"
+        php="
+    /**
+     * @Given user is in session as admin
+     * @Given user in session has role :role
+     */
+    public function sessionHasUserWithRole(string $role = 'admin'): void"></code-snippet>
+
+<article-paragraphs>
+    <p>
+        This snippet authenticates a user by a specified value in a given field and logs them into the session.
+    </p>
+</article-paragraphs>
+<code-snippet
+        gherkin="Given admin user is getting OK response from '/dashboard'"
+        php="
+     /**
+     * @Given admin user is getting OK response from :url
+     * @Given admin user is getting :status status code response from :url
+     * @Given user with :role role is getting OK response from :url
+     * @Given user with :role role is getting :status response from :url
+     * @Given user with :role role is getting OK response from :url using :method method
+     * @Given user with :role role is getting :status response from :url using :method method
+     */
+    public function adminUserIsGettingResponse(string $url, string $method = 'GET', int $status = Response::HTTP_OK, string $role = 'admin'): void"></code-snippet>

docs/elements/console.html

@@ -1 +1,105 @@
 <article-header>Console</article-header>
+
+<article-paragraphs>
+    <p>
+        Use <br>
+        <code class="text-sky-600">Blumilk\BLT\Features\Console</code> context <br>
+        or add <br>
+        <code class="text-sky-600">Blumilk\BLT\Features\Traits\Console</code> trait to test your application's
+        console features.
+    </p>
+</article-paragraphs>
+
+<section-header>Console Methods</section-header>
+<article-paragraphs>
+    <p>
+        The <code>Console</code> trait provides several methods to handle console commands within your Laravel application. These methods help ensure that your application's command-line interface is functioning as expected and can be tested effectively.
+    </p>
+</article-paragraphs>
+
+<article-paragraphs>
+    <p>
+        This snippet runs a specified Artisan command. It allows you to test scenarios where specific console commands need to be executed.
+        <br>
+        You can specify the command to run and capture its output and exit code.
+    </p>
+</article-paragraphs>
+<code-snippet gherkin="Given a command 'blt:init' is ran" php="
+    /**
+     * @Given a command :command is ran
+     * @Given a command :command is ran in console
+     * @throws BindingResolutionException
+     */
+    public function runArtisanCommand(string $command): void
+"></code-snippet>
+
+<article-paragraphs>
+    <p>
+        The <code>runCommandWithOptionsAndArguments</code> method runs a specified Artisan command with options and arguments provided in a table. This is useful for testing scenarios where commands require additional parameters.
+    </p>
+</article-paragraphs>
+
+<code-snippet gherkin="Given a command 'make:notification' is ran with:
+            | argument | NoParamsNotification |
+            | option   | force                |" php="
+    /**
+     * @Given a command :command is ran with:
+     * @throws BindingResolutionException
+     */
+    public function runCommandWithOptionsAndArguments(string $command, TableNode $table): void
+"></code-snippet>
+
+<article-paragraphs>
+    <p>
+        The <code>seeInConsole</code> method verifies that the console output contains a specified string. This is useful for ensuring that the command's output includes expected messages or results.
+    </p>
+</article-paragraphs>
+
+<code-snippet gherkin="Then console output contains 'created successfully'"
+              php="
+    /**
+     * @Then console output contains :output
+     * @Then console output should contain :output
+     */
+    public function seeInConsole(string $output): void
+"></code-snippet>
+
+<article-paragraphs>
+    <p>
+        The <code>consoleOutputIsNotEmpty</code> method verifies that the console output is not empty. This is useful for ensuring that the command produces output.
+    </p>
+</article-paragraphs>
+
+<code-snippet gherkin="Then console output is not empty" php="
+    /**
+     * @Then console output is not empty
+     */
+    public function consoleOutputIsNotEmpty(): void
+"></code-snippet>
+
+<article-paragraphs>
+    <p>
+        The <code>consoleOutputIsEmpty</code> method verifies that the console output is empty. This is useful for ensuring that the command produces no output.
+    </p>
+</article-paragraphs>
+
+<code-snippet gherkin="Then console output is empty" php="
+    /**
+     * @Then console output is empty
+     */
+    public function consoleOutputIsEmpty(): void
+"></code-snippet>
+
+<article-paragraphs>
+    <p>
+        The <code>consoleExitCodeIs</code> method verifies that the console exit code matches the expected code. This is useful for ensuring that the command exits with the correct status.
+    </p>
+</article-paragraphs>
+
+<code-snippet gherkin="Then console exit code is 0" php="
+    /**
+     * @Then console exit code is :code
+     * @Then console exit code should be :code
+     */
+    public function consoleExitCodeIs(int $code): void
+"></code-snippet>

docs/elements/cookies.html

@@ -0,0 +1,106 @@
+<article-header>Cookies</article-header>
+<article-paragraphs>
+    <p>
+        Use <br>
+        <code class="text-sky-600">Blumilk\BLT\Features\Cookies</code> context <br>
+        or add <br>
+        <code class="text-sky-600">Blumilk\BLT\Features\Traits\Cookies</code> trait to test your application's cookie features.
+    </p>
+</article-paragraphs>
+
+<section-header>Cookies Methods</section-header>
+<article-paragraphs>
+<p>
+The <code>Cookies</code> trait provides several methods to handle cookie operations within your Laravel application. These methods help ensure that your application's cookies are correctly set up and managed for testing purposes.
+</p>
+</article-paragraphs>
+<article-paragraphs>
+    <p>
+        This snippet sets a cookie with a specified name and value. It allows you to simulate setting cookies in your application.
+    </p>
+</article-paragraphs>
+<code-snippet
+        gherkin="When cookie :name with value :value is set"
+        php="
+    /**
+     * @When cookie :name with value :value is set
+     * @When cookie named :name with value :value is created
+     * @When cookie :name with value :value is added
+     */
+    public function setCookie(string $name, string $value): void
+    {
+        \$cookieFactory = \$this->getContainer()->make(CookieFactory::class);
+        \$cookieFactory->queue(\$name, \$value);
+    }"></code-snippet>
+<article-paragraphs>
+    <p>
+        The <code>assertCookieValue</code> method verifies that a cookie with the specified name has the expected value. This is useful for ensuring that cookies are set correctly in your application.
+    </p>
+</article-paragraphs>
+<code-snippet
+        gherkin="Then cookie :name should have value :value"
+        php="
+    /**
+     * @Then cookie :name should have value :value
+     */
+    public function assertCookieValue(string $name, string $value): void
+    {
+        \$cookieValue = \$this->request->cookies->get(\$name);
+        Assert::assertEquals(\$value, \$cookieValue, 'Cookie \$name does not have the expected value \$value.');
+    }"></code-snippet>
+<article-paragraphs>
+    <p>
+        The <code>deleteCookie</code> method removes a cookie with the specified name. This is useful for testing scenarios where you need to clear cookies.
+    </p>
+</article-paragraphs>
+<code-snippet
+        gherkin="When cookie :name is deleted"
+        php="
+    /**
+     * @When cookie :name is deleted
+     * @When cookie :name is removed
+     * @When cookie :name is cleared
+     */
+    public function deleteCookie(string \$name): void
+    {
+        \$cookieFactory = \$this->getContainer()->make(CookieFactory::class);
+        \$cookieFactory->queue(\$cookieFactory->forget(\$name));
+    }"></code-snippet>
+<article-paragraphs>
+    <p>
+        The <code>assertCookieNotExists</code> method verifies that a cookie with the specified name does not exist. This is useful for ensuring that cookies are properly deleted or not set.
+    </p>
+</article-paragraphs>
+<code-snippet
+        gherkin="Then the cookie :name should be missing"
+        php="
+    /**
+     * @Then the cookie :name should be missing
+     * @Then the cookie named :name should not be present
+     */
+    public function assertCookieNotExists(string \$name): void
+    {
+        \$cookieValue = \$this->request->cookies->get(\$name);
+        Assert::assertNull(\$cookieValue, 'Cookie \$name should not exist.');
+    }"></code-snippet>
+<article-paragraphs>
+    <p>
+        The <code>assertCookiesExist</code> method verifies that multiple cookies with specified names and values are present. This is useful for checking the state of several cookies in your application.
+    </p>
+</article-paragraphs>
+<code-snippet
+        gherkin="Then the following cookies should be present:
+            | name  | value  |
+            | foo   | bar    |"
+        php="
+    /**
+     * @Then the following cookies should be present:
+     * @Then the cookies should be set to:
+     */
+    public function assertCookiesExist(TableNode \$table): void
+    {
+        foreach (\$table as \$row) {
+            \$cookieValue = \$this->request->cookies->get(\$row['name']);
+            Assert::assertEquals(\$row['value'], \$cookieValue, 'Cookie {\$row['name']} does not have the expected value {\$row['value']}.');
+        }
+    }"></code-snippet>

docs/elements/hooks.html

@@ -0,0 +1,56 @@
+<section-header>Hooks</section-header>
+
+<article-paragraphs>
+    <p>Hooks are special methods that run at specified points in your test suite's lifecycle. They allow you to execute
+        code before and after certain events, providing a powerful mechanism to manage your test environment and ensure
+        consistency across your tests.</p>
+
+    <section-header>
+        Reboot after feature
+    </section-header>
+    <p>The <code class="text-sky-600">Blumilk\BLT\Features\Hooks\RebootAfterFeature</code> hook is designed to ensure that the system under test is reset to a clean state after each
+        feature is executed. </p>
+    <code-block>
+        /**
+        * @afterFeature
+        */
+        public static function rebootAfterFeature(): void
+        {
+        $bootstrapper = static::getRebootAfterFeatureBootstrapper();
+        $bootstrapper->boot();
+        }
+    </code-block>
+
+    <section-header>
+        Refresh database before scenario
+    </section-header>
+    <p>
+        The <code class="text-sky-600">Blumilk\BLT\Features\Hooks\RefreshDatabaseBeforeScenario</code> hook is designed to reset the database to a known state before each scenario
+        is executed. This ensures that each test scenario runs with a fresh and consistent database, which is crucial
+        for maintaining the integrity and reliability of your test results.
+    </p>
+    <code-block>
+        public function refreshDatabaseBeforeScenario(): void
+        {
+        $this->refreshDatabase();
+        }
+    </code-block>
+
+    <p class="font-semibold">To use hooks simply include them in your feature context</p>
+
+    <code-block>
+        use Blumilk\BLT\Features\Hooks\RefreshDatabaseBeforeScenario;
+
+        class FeatureContext extends Toolbox implements Context
+        {
+        use RefreshDatabaseBeforeScenario;
+
+        public function __construct()
+        {
+        $bootstrapper = new LaravelBootstrapper();
+        $bootstrapper->boot();
+        }
+        }
+    </code-block>
+
+</article-paragraphs>

docs/elements/http.html

@@ -356,7 +356,7 @@
     /**
      * @Then the response should contain JSON:
      */
-    public function aResponseShouldContainJson(TableNode $table): void"></code-snippet>
+    public function aResponseShouldContainJsonFragment(TableNode $table): void"></code-snippet>
 
 <article-paragraphs>
     <p>
@@ -403,6 +403,20 @@
      */
     public function aResponseShouldHaveHeaderEqualTo(string $header, string $value): void"></code-snippet>
 
+<article-paragraphs>
+    <p>
+        The <code>aResponseShouldHaveStatus</code> method verifies that the response status is equal to desired one. This is
+        useful for ensuring that the request has desired code.
+    </p>
+</article-paragraphs>
+
+<code-snippet
+        gherkin="Then the response should have status 200"
+        php="
+    /**
+     * @hen the response should have status :code
+     */
+    public function aResponseShouldHaveStatus(): void"></code-snippet>
 
 <article-paragraphs>
     <p>