Other languages: (🇩🇪) Deutsch

StrapiManual

Project Information

Using Cypress, a user manual for the CMS Strapi was automatically generated as part of my bachelor's thesis.
The basis for this project was the website at SKB-virtuell.
By chaining individual Cypress tests and generating reports with the help of Mocha custom reports, I was able to create HTML documents for each test suite and consolidate them into a manual.html.
For ease of use within the manual.html, features include automatic generation of a clickable table of contents, the "scroll-up" button, and the built-in search function available in standard web browsers using Ctrl+F.

Project Structure

• Cypress tests to monitor operations within the Strapi CMS:

  /cypress/e2e/...cy.js

• Output of HTML files generated by the Mocha custom reporter, along with related files:

  /cypress/reports-custom/...

• Collection of screenshots generated by Cypress:

  /cypress/screenshots/...

• Supporting Cypress configurations, including automatic logins via session cookies:

  /cypress/support/...

• Programmed Mocha custom reporter:

  /reporter/custom-reporter.js

Instructions

To generate your own user manual, follow these steps:

1. Install NodeJS

2. Install all dependencies:

   npm install

3. Install Cypress:

   npm install cypress

4. Create tests within /cypress/e2e/:

• The filename must match the description used in the Cypress test
  Example: 01 Test.cy.js as the filename for a test described as describe("01 Test", () => { ... });
• The filename or description must begin with a numerical value followed by a space for proper sorting
  Example: Use 01 Introduction.cy.js as the filename, or describe("01 Introduction", ...) as the description
• Test groups (it()) should also begin with a numerical value or optionally a sequence of letters for clarity
  Example: Use it("A First Operation")

5. Generate individual reports and the entire user manual manual.html
   Target directory: /cypress/reports-custom/

   npx cypress run

Customization Options

1. The appearance and styling of all elements can be adjusted through the CSS file:

   /cypress/reports-custom/styles.css

2. Changing or replacing logo.jpg allows you to customize the logo within manual.html:

   /cypress/reports-custom/logo.jpg

3. You can customize the text at the end of manual.html by modifying footer.txt:

   /cypress/reports-custom/footer.txt

Side notes

Commenting on commands

By commenting out commands, they won't be executed by Cypress during the test run, but they still appear as instructions in the respective HTML output and, consequently, in manual.html:

// cy.visit("www.example.com");

This can be advantageous when you only want to provide an instruction to the end user, but the execution within a test could have significant consequences.

---

Text Output

It is possible to generate text outputs for the user manual using cy.log(). Different display formats are possible using the optional prefixes hint, warning, and attention. To make these recognizable by the custom reporter, a colon : and a space are required after them.
Example:

cy.log("warning: This is a warning and will be highlighted accordingly!");

In the output in the manual, the corresponding prefixes (if present) are automatically removed, and the following text is formatted accordingly to the prefix.

---

Credentials

By creating a credentials.json, the automatic login process can be used with cy.login():

{
  "user": "user@email.com",
  "password": "password"
}

The credentials.json must be created manually at this location:

/cypress/support/credentials.json

---

Server Environment

To correctly and completely display manual.html with the inclusion of manual.js, you can, for example, set up a local server environment using Live Server from VSCode.

---

PDF Generation

The script generatePDF.js allows for the generation of a complete PDF using Puppeteer, containing all the information from manual.html. To execute this, it is assumed that manual.html is being run on a local server environment (Port: 5500) (see the note on Server Environment).

Navigate to the corresponding folder where generatePDF.js is located:

cd .\cypress\reports-custom\

To execute, use the following command:

node node generatePDF.js

The generated manual.pdf is now located in the corresponding folder \cypress\reports-custom\ .

The default path and port for the server environment can be adjusted in \cypress\reports-custom\generatePDF.js:

http://localhost:5500/cypress/reports-custom/manual.html