@shopware-ag/acceptance-test-suite 2.3.10 → 2.4.0

package/README.md

@@ -15,6 +15,7 @@ This test suite is an extension to [Playwright](https://playwright.dev/) to easi
 * [Actor Pattern](#actor-pattern)
 * [Data Fixtures](#data-fixtures)
 * [Code Contribution](#code-contribution)
+* [Best practices](#best-practices)
 
 ## Installation
 Start by creating your own [Playwright](https://playwright.dev/docs/intro) project.
@@ -374,4 +375,32 @@ If you create your own data fixtures make sure to import and merge them in your
 ## Code Contribution
 You can contribute to this project via its [official repository](https://github.com/shopware/acceptance-test-suite/) on GitHub.  
 
-This project uses [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/). Please make sure to form your commits accordingly to the spec.
+This project uses [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/). Please make sure to form your commits accordingly to the spec.
+
+## Best practices
+
+A good first read about this is the official [playwright best practices page](https://playwright.dev/docs/best-practices). It describes the most important practices which should also be followed when writing acceptance tests for Shopware.
+
+The most important part is [test isolation](https://playwright.dev/docs/best-practices#make-tests-as-isolated-as-possible) which helps to prevent flaky behavior and enables the test to be run in parallel and on systems with an unknown state.
+
+
+### Dos
+
+- use fixtures or the [`TestDataService`](./src/services/TestDataService.ts)
+- create all the data that is required for your test case. That includes sales channels, customers and users (the page fixtures handle most of the common use cases)
+- if you need specific settings for your test, set it explicitly for the user/customer/sales channel
+- directly jump to detail pages with the id of the entities you've created
+    - if that's no possible, use the search with a unique name to filter lists to just that single entity
+
+### Don'ts
+
+- do not expect lists/tables to only contain one item, leverage unique ids/names to open or find your entity instead
+- same with helper functions, do not except to only get item back from the API. Always a unique criteria to the API call
+- avoid unused fixtures: if you request a fixture but don't use any data from the fixture, the test or fixture should be refactored
+- do not depend on implicit configuration and existing data. Examples:
+    - rules
+    - flows
+    - categories
+- do not expect the shop to have the defaults en_GB and EUR
+- do not change global settings (sales channel is ok, because it's created by us)
+  - basically everything in Settings that is not specific to a sales channel (tax, search, etc.)

package/dist/index.d.mts

@@ -70,9 +70,61 @@ declare class StoreApiContext {
     head<PAYLOAD>(url: string, options?: RequestOptions<PAYLOAD>): Promise<APIResponse>;
 }
 
+interface Email {
+    fromName: string;
+    fromAddress: string;
+    toName: string;
+    toAddress: string;
+    subject: string;
+    emailId: string;
+}
+declare class MailpitApiContext {
+    context: APIRequestContext;
+    constructor(context: APIRequestContext);
+    /**
+     * Fetches email headers based on the recipient's email address.
+     * @param email - The email address of the recipient.
+     * @returns An Email object containing the email headers.
+     */
+    getEmailHeaders(email: string): Promise<Email>;
+    /**
+     * Retrieves the body content of the latest email as an HTML string.
+     * @returns The HTML content of the latest email.
+     */
+    getEmailBody(): Promise<string>;
+    /**
+     * Generates the full email content, combining headers and body.
+     * @param email - The email address to fetch headers for.
+     * @returns The full email content as a string.
+     */
+    generateEmailContent(email: string): Promise<string>;
+    /**
+     * Retrieves the plain text content of the latest email.
+     * @returns The plain text content of the latest email.
+     */
+    getRenderMessageTxt(): Promise<string>;
+    /**
+     * Extracts the first URL found in the plain text content of the latest email.
+     * @returns The first URL found in the email content.
+     * @throws An error if no URL is found in the email content.
+     */
+    getLinkFromMail(): Promise<string>;
+    /**
+     * Deletes a specific email by ID if provided, or deletes all emails if no ID is provided.
+     * @param emailId - The ID of the email to delete (optional).
+     */
+    deleteMail(emailId?: string): Promise<void>;
+    /**
+     * Creates a new EmailApiContext instance with the appropriate configuration.
+     * @returns A promise that resolves to an EmailApiContext instance.
+     */
+    static create(baseURL: string): Promise<MailpitApiContext>;
+}
+
 interface ApiContextTypes {
     AdminApiContext: AdminApiContext;
     StoreApiContext: StoreApiContext;
+    MailpitApiContext: MailpitApiContext;
 }
 
 interface PageContextTypes {
@@ -460,7 +512,7 @@ declare class TestDataService {
     /**
      * Will delete all entities created by the data service via sync API.
      */
-    cleanUp(): Promise<playwright_core.APIResponse>;
+    cleanUp(): Promise<playwright_core.APIResponse | null>;
     /**
      * Convert a JS date object into a date-time compatible string.
      *

package/dist/index.d.ts

@@ -70,9 +70,61 @@ declare class StoreApiContext {
     head<PAYLOAD>(url: string, options?: RequestOptions<PAYLOAD>): Promise<APIResponse>;
 }
 
+interface Email {
+    fromName: string;
+    fromAddress: string;
+    toName: string;
+    toAddress: string;
+    subject: string;
+    emailId: string;
+}
+declare class MailpitApiContext {
+    context: APIRequestContext;
+    constructor(context: APIRequestContext);
+    /**
+     * Fetches email headers based on the recipient's email address.
+     * @param email - The email address of the recipient.
+     * @returns An Email object containing the email headers.
+     */
+    getEmailHeaders(email: string): Promise<Email>;
+    /**
+     * Retrieves the body content of the latest email as an HTML string.
+     * @returns The HTML content of the latest email.
+     */
+    getEmailBody(): Promise<string>;
+    /**
+     * Generates the full email content, combining headers and body.
+     * @param email - The email address to fetch headers for.
+     * @returns The full email content as a string.
+     */
+    generateEmailContent(email: string): Promise<string>;
+    /**
+     * Retrieves the plain text content of the latest email.
+     * @returns The plain text content of the latest email.
+     */
+    getRenderMessageTxt(): Promise<string>;
+    /**
+     * Extracts the first URL found in the plain text content of the latest email.
+     * @returns The first URL found in the email content.
+     * @throws An error if no URL is found in the email content.
+     */
+    getLinkFromMail(): Promise<string>;
+    /**
+     * Deletes a specific email by ID if provided, or deletes all emails if no ID is provided.
+     * @param emailId - The ID of the email to delete (optional).
+     */
+    deleteMail(emailId?: string): Promise<void>;
+    /**
+     * Creates a new EmailApiContext instance with the appropriate configuration.
+     * @returns A promise that resolves to an EmailApiContext instance.
+     */
+    static create(baseURL: string): Promise<MailpitApiContext>;
+}
+
 interface ApiContextTypes {
     AdminApiContext: AdminApiContext;
     StoreApiContext: StoreApiContext;
+    MailpitApiContext: MailpitApiContext;
 }
 
 interface PageContextTypes {
@@ -460,7 +512,7 @@ declare class TestDataService {
     /**
      * Will delete all entities created by the data service via sync API.
      */
-    cleanUp(): Promise<playwright_core.APIResponse>;
+    cleanUp(): Promise<playwright_core.APIResponse | null>;
     /**
      * Convert a JS date object into a date-time compatible string.
      *

package/dist/index.mjs

@@ -393,16 +393,16 @@ const test$b = test$d.extend({
   ]
 });
 
-var __defProp$s = Object.defineProperty;
-var __defNormalProp$s = (obj, key, value) => key in obj ? __defProp$s(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __publicField$s = (obj, key, value) => {
-  __defNormalProp$s(obj, typeof key !== "symbol" ? key + "" : key, value);
+var __defProp$t = Object.defineProperty;
+var __defNormalProp$t = (obj, key, value) => key in obj ? __defProp$t(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$t = (obj, key, value) => {
+  __defNormalProp$t(obj, typeof key !== "symbol" ? key + "" : key, value);
   return value;
 };
 const _AdminApiContext = class _AdminApiContext {
   constructor(context, options) {
-    __publicField$s(this, "context");
-    __publicField$s(this, "options");
+    __publicField$t(this, "context");
+    __publicField$t(this, "options");
     this.context = context;
     this.options = options;
   }
@@ -494,7 +494,7 @@ const _AdminApiContext = class _AdminApiContext {
     return this.context.head(url, options);
   }
 };
-__publicField$s(_AdminApiContext, "defaultOptions", {
+__publicField$t(_AdminApiContext, "defaultOptions", {
   app_url: process.env["APP_URL"],
   client_id: process.env["SHOPWARE_ACCESS_KEY_ID"],
   client_secret: process.env["SHOPWARE_SECRET_ACCESS_KEY"],
@@ -504,16 +504,16 @@ __publicField$s(_AdminApiContext, "defaultOptions", {
 });
 let AdminApiContext = _AdminApiContext;
 
-var __defProp$r = Object.defineProperty;
-var __defNormalProp$r = (obj, key, value) => key in obj ? __defProp$r(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __publicField$r = (obj, key, value) => {
-  __defNormalProp$r(obj, typeof key !== "symbol" ? key + "" : key, value);
+var __defProp$s = Object.defineProperty;
+var __defNormalProp$s = (obj, key, value) => key in obj ? __defProp$s(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$s = (obj, key, value) => {
+  __defNormalProp$s(obj, typeof key !== "symbol" ? key + "" : key, value);
   return value;
 };
 const _StoreApiContext = class _StoreApiContext {
   constructor(context, options) {
-    __publicField$r(this, "context");
-    __publicField$r(this, "options");
+    __publicField$s(this, "context");
+    __publicField$s(this, "options");
     this.context = context;
     this.options = options;
   }
@@ -572,12 +572,122 @@ const _StoreApiContext = class _StoreApiContext {
     return this.context.head(url, options);
   }
 };
-__publicField$r(_StoreApiContext, "defaultOptions", {
+__publicField$s(_StoreApiContext, "defaultOptions", {
   app_url: process.env["APP_URL"],
   ignoreHTTPSErrors: true
 });
 let StoreApiContext = _StoreApiContext;
 
+var __defProp$r = Object.defineProperty;
+var __defNormalProp$r = (obj, key, value) => key in obj ? __defProp$r(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$r = (obj, key, value) => {
+  __defNormalProp$r(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+class MailpitApiContext {
+  constructor(context) {
+    __publicField$r(this, "context");
+    this.context = context;
+  }
+  /**
+   * Fetches email headers based on the recipient's email address.
+   * @param email - The email address of the recipient.
+   * @returns An Email object containing the email headers.
+   */
+  async getEmailHeaders(email) {
+    const response = await this.context.get("/api/v1/search", {
+      params: {
+        kind: "To.Address",
+        query: email
+      }
+    });
+    const responseJson = await response.json();
+    return {
+      fromName: responseJson.messages[0].From.Name,
+      fromAddress: responseJson.messages[0].From.Address,
+      toName: responseJson.messages[0].To[0].Name,
+      toAddress: responseJson.messages[0].To[0].Address,
+      subject: responseJson.messages[0].Subject,
+      emailId: responseJson.messages[0].ID
+    };
+  }
+  /**
+   * Retrieves the body content of the latest email as an HTML string.
+   * @returns The HTML content of the latest email.
+   */
+  async getEmailBody() {
+    const response = await this.context.get("view/latest.html");
+    const buffer = await response.body();
+    const htmlString = buffer.toString("utf-8");
+    return htmlString;
+  }
+  /**
+   * Generates the full email content, combining headers and body.
+   * @param email - The email address to fetch headers for.
+   * @returns The full email content as a string.
+   */
+  async generateEmailContent(email) {
+    const headers = await this.getEmailHeaders(email);
+    const htmlTemplate = await this.getEmailBody();
+    const headerSection = `
+       <div style="font-family:arial; font-size:16px;" id="email-container">
+        <p id="from"><strong>From:</strong> ${headers.fromName} &lt;${headers.fromAddress}&gt;</p>
+        <p id="to"><strong>To:</strong> ${headers.toName} &lt;${headers.toAddress}&gt;</p>
+        <p id="subject"><strong>Subject:</strong> ${headers.subject}</p>
+      </div> 
+    `;
+    const emailContent = headerSection + htmlTemplate;
+    return emailContent;
+  }
+  /**
+   * Retrieves the plain text content of the latest email.
+   * @returns The plain text content of the latest email.
+   */
+  async getRenderMessageTxt() {
+    const response = await this.context.get("view/latest.txt");
+    const buffer = await response.body();
+    const text = buffer.toString("utf-8");
+    return text;
+  }
+  /**
+   * Extracts the first URL found in the plain text content of the latest email.
+   * @returns The first URL found in the email content.
+   * @throws An error if no URL is found in the email content.
+   */
+  async getLinkFromMail() {
+    const textContent = await this.getRenderMessageTxt();
+    const urlMatch = textContent.match(/https?:\/\/[^\s]+/);
+    if (urlMatch && urlMatch.length > 0) {
+      return urlMatch[0];
+    }
+    throw new Error("No URL found in the email content");
+  }
+  /**
+   * Deletes a specific email by ID if provided, or deletes all emails if no ID is provided.
+   * @param emailId - The ID of the email to delete (optional).
+   */
+  async deleteMail(emailId) {
+    const data = emailId ? { IDs: [emailId] } : {};
+    await this.context.delete(`api/v1/messages`, { data });
+  }
+  /**
+   * Creates a new EmailApiContext instance with the appropriate configuration.
+   * @returns A promise that resolves to an EmailApiContext instance.
+   */
+  static async create(baseURL) {
+    const extraHTTPHeaders = {
+      "Accept": "application/json",
+      "Content-Type": "application/json"
+    };
+    const context = await request.newContext({
+      baseURL,
+      ignoreHTTPSErrors: true,
+      extraHTTPHeaders
+    });
+    return new MailpitApiContext(context);
+  }
+}
+
 const test$a = test$d.extend({
   AdminApiContext: [
     async ({}, use) => {
@@ -597,6 +707,13 @@ const test$a = test$d.extend({
       await use(storeApiContext);
     },
     { scope: "worker" }
+  ],
+  MailpitApiContext: [
+    async ({}, use) => {
+      const mailpitApiContext = await MailpitApiContext.create(process.env["MAILPIT_BASE_URL"]);
+      await use(mailpitApiContext);
+    },
+    { scope: "worker" }
   ]
 });
 
@@ -1400,7 +1517,7 @@ class TestDataService {
    */
   async cleanUp() {
     if (!this.shouldCleanUp) {
-      return Promise.reject();
+      return null;
     }
     const priorityDeleteOperations = {};
     const deleteOperations = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopware-ag/acceptance-test-suite",
-  "version": "2.3.10",
+  "version": "2.4.0",
   "description": "Shopware Acceptance Test Suite",
   "author": "shopware AG",
   "license": "MIT",