Merge branch 'refs/heads/#73-test-documentation' into community-stand…

…ards

.gitignore

@@ -1,5 +1,4 @@
 /.idea
 /.composer
 /vendor
-
 composer.lock

config/blt.php

@@ -11,7 +11,8 @@
     "namespaces" => [
         "default" => "App\\",
         "types" => [
-            "User" => "App\Models\User",
+            "role" => "Spatie\Permission\Models\Role",
+            "user" => "App\Models\User",
         ],
     ],
     "helpers" => [

docs/customHighlight.css

@@ -0,0 +1,66 @@
+.hljs-keyword,
+.hljs-selector-tag,
+.hljs-literal,
+.hljs-section,
+.hljs-doctag,
+.hljs-title {
+    color: #c678dd;
+}
+
+.hljs-string,
+.hljs-meta .hljs-string,
+.hljs-attr,
+.hljs-template-tag,
+.hljs-template-variable,
+.hljs-addition {
+    color: #98c379;
+}
+
+.hljs-comment,
+.hljs-quote,
+.hljs-deletion {
+    color: #5c6370;
+}
+
+.hljs-variable,
+.hljs-template-variable,
+.hljs-attribute,
+.hljs-tag,
+.hljs-name,
+.hljs-regexp,
+.hljs-link,
+.hljs-selector-id,
+.hljs-selector-class {
+    color: #1f8ef1;
+}
+
+.hljs-number,
+.hljs-meta,
+.hljs-built_in,
+.hljs-builtin-name,
+.hljs-literal,
+.hljs-type,
+.hljs-params,
+.hljs-class .hljs-title {
+    color: #d19a66;
+}
+
+.hljs-symbol,
+.hljs-bullet,
+.hljs-subst,
+.hljs-meta,
+.hljs-function,
+.hljs-title,
+.hljs-keyword,
+.hljs-selector-tag,
+.hljs-selector-pseudo {
+    color: #61dafb; 
+}
+
+.hljs-emphasis {
+    font-style: italic;
+}
+
+.hljs-strong {
+    font-weight: bold;
+}

docs/elements/application.html

@@ -0,0 +1,75 @@
+<article-header>Application</article-header>
+
+<article-paragraphs>
+    <p>
+        Use <br>
+        <code class="text-sky-600">Blumilk\BLT\Features\Application</code> context <br>
+        or add <br>
+        <code class="text-sky-600">Blumilk\BLT\Features\Traits\Application</code> trait to test your application's
+        application features.
+    </p>
+</article-paragraphs>
+
+<article-paragraphs>
+    <p>
+        In the development and testing of Laravel applications, mocking services is quite important. By mocking
+        services, you can isolate and test specific parts of your application without relying on external dependencies.
+        This ensures your tests are reliable and focused.
+    </p>
+    <p>
+        This chapter covers the <code>Application</code> trait in the BLT package, which provides methods to mock
+        services in your Laravel application during tests. You will learn how to mock individual services and multiple
+        services at once using this trait.
+    </p>
+</article-paragraphs>
+
+<section-header>Mocking individual services</section-header>
+<article-paragraphs>
+    <p>
+        The following example demonstrates how to mock a specified service with a given mock class. This method ensures
+        that the specified service is replaced by the mock during the test scenario.
+    </p>
+</article-paragraphs>
+
+<code-snippet
+        gherkin='Given there is "App\Services\NotificationService" service mocked with "App\Mocks\NotificationServiceMock"'
+        php='/**
+  * @Given there is :service service mocked with :mock
+  * @throws BindingResolutionException
+  */
+ public function thereIsServiceMocked(string $service, string $mock): void'></code-snippet>
+
+<article-paragraphs>
+    <p>
+        In this example, the <code>NotificationService</code> is replaced with <code>NotificationServiceMock</code>.
+        This allows the test to run with the mocked version of the service.
+    </p>
+</article-paragraphs>
+
+<section-header>Mocking multiple services</section-header>
+<article-paragraphs>
+    <p>
+        The following example demonstrates how to mock multiple services at once using a table to specify the services
+        and their respective mocks. This method ensures that each specified service is replaced by the corresponding
+        mock during the test scenario.
+    </p>
+</article-paragraphs>
+
+<code-snippet
+        gherkin='Given there are services mocked:
+      | service                    | mock                          |
+      | App\Services\EmailService  | App\Mocks\EmailServiceMock    |
+      | App\Services\PaymentService| App\Mocks\PaymentServiceMock  |'
+        php='/**
+  * @Given there are services mocked:
+  * @throws BindingResolutionException
+  */
+ public function thereAreServicesMocked(TableNode $table): void'></code-snippet>
+
+<article-paragraphs>
+    <p>
+        In this example, both the <code>EmailService</code> and <code>PaymentService</code> are replaced with their
+        respective mocks, <code>EmailServiceMock</code> and <code>PaymentServiceMock</code>. This allows the test to run
+        with the mocked versions of these services.
+    </p>
+</article-paragraphs>

docs/elements/authentication.html

@@ -0,0 +1,188 @@
+<article-header>Authentication</article-header>
+
+<article-paragraphs>
+    <p>
+        Use <br>
+        <code class="text-sky-600">Blumilk\BLT\Features\Authentication</code> context <br>
+        or add <br>
+        <code class="text-sky-600">Blumilk\BLT\Features\Traits\Authentication</code> trait to test your application's
+        authentication features.
+    </p>
+</article-paragraphs>
+
+<section-header>Authentication Checks and Operations</section-header>
+<article-paragraphs>
+    <p>
+        The <code>Authentication</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 authenticated in session as :value in :field field
+     * @throws BindingResolutionException
+     */
+    public function userIsAuthenticatedInSessionAs(string $value, string $field): void"></code-snippet>
+
+<article-paragraphs>
+    <p>
+        This snippet logs out any authenticated user from the session.
+    </p>
+</article-paragraphs>
+<code-snippet
+        gherkin="Given there is no user authenticated in session"
+        php="
+    /**
+     * @Given there is no user authenticated in session
+     * @throws BindingResolutionException
+     */
+    public function thereIsNoUserAuthenticatedInSession(): void"></code-snippet>
+<article-paragraphs>
+    <p>
+        This snippet authenticates a user with the specified attributes.
+    </p>
+</article-paragraphs>
+<code-snippet
+        gherkin="Given the user is authenticated with attributes:
+        |email|[email protected]|
+        |name |admin            |"
+        php="
+    /**
+     * @Given the user is authenticated with attributes:
+     */
+    public function userIsAuthenticatedWithAttributes(TableNode $table): void"></code-snippet>
+
+<article-paragraphs>
+    <p>
+        This snippet logs out any authenticated user, ensuring no user is authenticated.
+    </p>
+</article-paragraphs>
+<code-snippet
+        gherkin="Given there is an unauthenticated user"
+        php="
+    /**
+     * @Given there is an unauthenticated user
+     * @throws BindingResolutionException
+     */
+    public function thereIsAnUnauthenticatedUser(): void"></code-snippet>
+
+<article-paragraphs>
+    <p>
+        This snippet authenticates a user with a specified email.
+    </p>
+</article-paragraphs>
+<code-snippet
+        gherkin="Given there is an authenticated user with email '[email protected]'"
+        php="
+    /**
+     * @Given there is an authenticated user with email :email
+     * @throws BindingResolutionException
+     */
+    public function thereIsAuthenticatedUserWithEmail(string $email): void"></code-snippet>
+
+<article-paragraphs>
+    <p>
+        This snippet asserts that no user is authenticated in the session.
+    </p>
+</article-paragraphs>
+<code-snippet
+        gherkin="Then no user is authenticated in session"
+        php="
+    /**
+     * @Then no user is authenticated in session
+     * @throws BindingResolutionException
+     */
+    public function noUserAuthenticatedInSession(): void"></code-snippet>
+
+<article-paragraphs>
+    <p>
+        This snippet asserts that the authenticated user in the session has a specific value in a given field.
+    </p>
+</article-paragraphs>
+<code-snippet
+        gherkin="Then user authenticated in session has '[email protected]' value in email field"
+        php="
+    /**
+     * @Then user authenticated in session has :value value in :field field
+     * @throws BindingResolutionException
+     */
+    public function userAuthenticatedInSessionIs(string $value, string $field): void"></code-snippet>
+
+<article-paragraphs>
+    <p>
+        This snippet asserts that the authenticated user's email matches the specified value.
+    </p>
+</article-paragraphs>
+<code-snippet
+        gherkin="Then the authenticated user email should be '[email protected]'"
+        php="
+    /**
+     * @Then the authenticated user email should be :email
+     * @throws BindingResolutionException
+     */
+    public function authenticatedUsersEmailShouldBe(string $email): void"></code-snippet>
+
+<article-paragraphs>
+    <p>
+        This snippet asserts that the authenticated user has a specific attribute with a given value.
+    </p>
+</article-paragraphs>
+<code-snippet
+        gherkin="Then the authenticated user should have the attribute email with value '[email protected]'"
+        php="
+    /**
+     * @Then the authenticated user should have the attribute :attribute with value :value
+     * @throws BindingResolutionException
+     */
+    public function authenticatedUserShouldHaveAttribute(string $attribute, $value): void"></code-snippet>
+
+<article-paragraphs>
+    <p>
+        This snippet logs out the authenticated user and asserts that no user is authenticated.
+    </p>
+</article-paragraphs>
+<code-snippet
+        gherkin="Then the user should be able to logout"
+        php="
+    /**
+     * @Then the user should be able to logout
+     * @throws BindingResolutionException
+     */
+    public function userShouldBeAbleToLogout(): void"></code-snippet>
+
+<article-paragraphs>
+    <p>
+        This snippet asserts that the authenticated user is redirected to a specified URL.
+    </p>
+</article-paragraphs>
+<code-snippet
+        gherkin="Then the authenticated user should be redirected to '/dashboard'"
+        php="
+    /**
+     * @Then the authenticated user should be redirected to :url
+     * @throws BindingResolutionException
+     */
+    public function authenticatedUserShouldBeRedirectedTo(string $url): void"></code-snippet>
+
+<article-paragraphs>
+    <p>
+        This snippet asserts that a user with a specified email cannot access a given URL.
+    </p>
+</article-paragraphs>
+<code-snippet
+        gherkin="Then the user with email '[email protected]' should not be able to access '/dashboard'"
+        php="
+    /**
+     * @Then the user with email :email should not be able to access :url
+     * @throws BindingResolutionException
+     */
+    public function userWithEmailShouldNotBeAbleToAccess(string $email, string $url): void"></code-snippet>