karatetools-oss

Overview

This library is a general purpose library that can be used by any Karate project.

The Karate Tools Open Source Repository is organized as follows:

code - Karate Tools Open Source codebase with the corresponding unit and integration tests
- 👩‍💻 karatetools-oss-code
e2e/karate - Karate Tools Open Source karate tests
- 🧪 karatetools-oss-karate-test
docs - Karate Tools Open Source documentation based on asciidoc and antora
- 📄 karatetools-oss-docs

├── code (1)
│   ├── archetype (2)
│   │   └── src
│   │       └── test
│   │           ├── java
│   │           └── resources
│   ...
│   └── starter (2)
├── docs (3)
│   ├── build (4)
│   ├── node_modules (4)
│   ├── src
│   │   └── modules (5)
│   │       ├── HOME
│   │       │   ├── images
│   │       │   └── pages
│   │       ...
│   │       └── release
│   └── supplemental-ui (6)
└── e2e
    └── karate (7)
        └── src
            └── test
                ├── java
                └── resources

1	codebase root directory
2	codebase maven modules
3	documentation root directory
4	documentation build and node directories
5	documentation antora asciidoc modules
6	documentation antora UI assets (page templates, CSS, JavaScript, images, etc.)
7	karate-test maven module root directory

The main code modules are:

👩‍💻 karatetools-oss-archetype: archetype to generate a karate project from scratch with the necessary configurations and utilities for the execution of tests.
👩‍💻 karatetools-oss-clients: clients to interact with relational databases via JDBC (MariaDB and PostgreSQL), MongoDB, Kafka and JMS (Active MQ)
👩‍💻 karatetools-oss-generators: generators of tests from Open API
👩‍💻 karatetools-oss-runner: karate runner and all related utilities (authentication, JWT tokens, karate base configuration, karate utils, karate mocks, karate cache, karate results and reports, …)
👩‍💻 karatetools-oss-starter: starter module to include the generators, clients and runner in a Karate project.

It includes test open api modules:

👩‍💻 karatetools-oss-openapi-test: Open API test specifications for the karate tools tests with two sub-modules:
- 👩‍💻 karatetools-oss-xxx-api-rest-stable: api to test the test generation tools
- 👩‍💻 karatetools-oss-xxx-external-api-rest-stable: api to test the mock generation tools

It includes a spring boot module:

👩‍💻 karatetools-oss-boot: spring boot application with a simple rest api implementing the Open API test specification and docker containers to be used as target for the karate tools tests (runner, rest, auth, jdbc, mongodb, kafka, jms, …)

The karate test module is defined in the e2e/karate folder:

🧪 karatetools-oss-karate-test: karate module to test the karate tools.
- This module has been generated using the ⚙️ Karate Tools - Archetype
- Includes auto-generated tests and mocks for sample api (karatetools-oss-openapi-test)
- uses the karatetools-oss-starter to test the karate clients and the sample application (karatetools-oss-boot) and containers.

The documentation is defined in the docs folder:

📄 karatetools-oss-docs: documentation of the karate tools based on asciidoc and antora.

Figure 1. Karate Tools Open Source Modules

karatetools-oss-code

The following sections will describe the code structure, to be able to find easily the location of the code to be added or modified.

👩‍💻 karatetools-oss-archetype
👩‍💻 karatetools-oss-clients
👩‍💻 karatetools-oss-generators
👩‍💻 karatetools-oss-runner
👩‍💻 karatetools-oss-starter
👩‍💻 karatetools-oss-boot
👩‍💻 karatetools-oss-openapi-test

The tests to be executed for the code modules are:

Unit & Mutation Tests:
- Unit tests are used to test the classes and methods of the code modules.
- Mutation tests are used to verify that the unit tests are effective.
Integration tests:
- Integration tests are used to test the code modules together with external dependencies.
- These tests are supported by a set of docker containers located in code/src/test/resources/compose

Unit, mutation and integration tests are required as status checks in the CI/CD pipeline pull request approval process. The level of coverage for each type of test must reach at least the defined threshold.

Karate tests are defined in the e2e/karate folder and are executed in the karatetools-oss-karate-test module.

Table 1. Tests Execution (Locally)
test	command	report	verification
unit	`cd code` `mvn clean verify -DskipITs -DfailIfNoTests=false -Dmaven.test.failure.ignore=false`	`code/jacoco-report-aggregate/target/site/jacoco-aggregate/index.html`	all tests pass and the code coverage generated by unit tests is at least 90%
mutation	`cd code` `mvn clean verify pitest:mutationCoverage pitest:report-aggregate-module -DskipITs`	`code/target/pit-reports/index.html`	all tests pass and the mutation coverage is at least 90%
integration	`cd code` `mvn clean verify -DskipUTs -DfailIfNoTests=false -Dmaven.test.failure.ignore=false`	`code/jacoco-report-aggregate/target/site/jacoco-aggregate-it/index.html`	all tests pass and the code coverage generated by integration tests is at least 80%

Table 2. Tests Execution (Github)
test	command	report	verification
unit	workflow dispatch automatically on PR	workflow execution reports	automatically on workflow execution
mutation	workflow dispatch automatically on PR	workflow execution reports	automatically on workflow execution
integration	workflow dispatch automatically on PR	workflow execution reports	automatically on workflow execution
compatibility	workflow dispatch automatically on PR	workflow execution reports	automatically on workflow execution

karatetools-oss-archetype

What is Archetype? In short, Archetype is a Maven project templating toolkit. An archetype is defined as an original pattern or model from which all other things of the same kind are made.

The karatetools-oss-archetype module povides the templates and scripts to generate karate-test modules.

This module has the following structure:

Figure 2. Karate Tools Archetype Overview

It includes the following files:

code/archetype/
├── pom.xml
└── src
    ├── main
    │   └── resources
    │       ├── META-INF
    │       │   ├── archetype-post-generate.groovy (1)
    │       │   └── maven
    │       │       └── archetype-metadata.xml (2)
    │       └── archetype-resources (3)
    │           ├── .gitignore (4)
    │           ├── .tool-versions (5)
    │           ├── pom.xml (6)
    │           └── src
    │               └── test
    │                   ├── java
    │                   │   └── KarateRunnerTest.java (7)
    │                   └── resources
    │                       ├── config (8)
    │                       │   ├── db
    │                       │   │   ├── mariadb-config-local.yml
    │                       │   │   ├── mongodb-config-local.yml
    │                       │   │   └── postgresql-config-local.yml
    │                       │   ├── jms
    │                       │   │   └── activemq-config-local.yml
    │                       │   └── kafka
    │                       │       └── kafka-config-local.yml
    │                       ├── config-local.yml (9)
    │                       ├── config.yml (9)
    │                       ├── jwt
    │                       │   └── default-jwt.yml (10)
    │                       ├── karate-config.js (11)
    │                       ├── logback-test.xml (12)
    │                       └── mocks
    │                           └── templates
    │                               └── standalone (13)
    │                                   └── .gitkeep
    └── test
        └── resources
            └── projects (14)
                ├── all (15)
                │   ├── archetype.properties (16)
                │   ├── goal.txt (17)
                │   └── reference (18)
                │       ├── .gitignore
                │       ├── .tool-versions
                │       ├── pom.xml
                │       └── ...
                ├── default (15)
                │   ├── archetype.properties (16)
                │   ├── goal.txt (17)
                │   └── reference (18)
                │       ├── .gitignore
                │       ├── .tool-versions
                │       ├── pom.xml
                │       └── ...
                ...

1	post-processing script to choose the files to include based on the archetype properties which are prompted to the user.
2	archetype descriptor, metadata defining the archetype properties, files and directories, and the post-processing script.
3	the prototype files that are copied by the archetype plugin to the target module
4	prototype: Git ignore file
5	prototype: Tools version manager file
6	prototype: Karate pom file
7	prototype: Java Test Runner
8	prototype: karate clients configuration files templates
9	prototype: Configuration Files (general and environment specific)
10	prototype: Karate Authentication Default JWT
11	prototype: Karate-config file
12	prototype: logback configuration file
13	prototype: karate mocks folder to define standalone mock templates
14	test projects to test the archetype generation with different configurations
15	test: project folder
16	test: archetype properties (groupId, artifactId, version, …)
17	test: maven goal to be executed for the project test, for example: `clean validate`
18	test: expected output files

Any changes made in the prototype files and/or processing scripts must be reflected in the corresponding output project tests.

karatetools-oss-clients

The karatetools-oss-clients module includes the following core and support packages.

The core packages are:

📦 dev.inditex.karate.db: JDBC client to interact with relational databases. The included drivers are:
- 🛢️ MariaDB
- 🛢️ PostgreSQL
📦 dev.inditex.karate.mongodb: MongoDB client to interact with MongoDB.
📦 dev.inditex.karate.kafka: Kafka clients to interact with Kafka.
📦 dev.inditex.karate.jms: JMS client to interact with JMS. The included clients are:
- ✉️ Active MQ Artemis

The support packages are:

📦 dev.inditex.karate.logging: logging utilities to log the clients methods.
📦 dev.inditex.karate.parser: parser utilities to parse the clients configuration files and inject system properties.

Figure 3. Karate Tools Clients Overview

karatetools-oss-generators

The karatetools-oss-generators module includes the following packages:

📦 dev.inditex.karate.openapi: Open API generator to create test scenarios, test data and external services mocks from Open API specifications.
📦 dev.inditex.karate.console: request user input from the console (which API specification file to use, which operations to generate, etc).

Figure 4. Karate Tools Generators Overview

karatetools-oss-runner

The karatetools-oss-runner module includes the following packages:

📦 dev.inditex.karate.jwt: JWT generator to create JWT tokens for authentication and authorization purposes in Karate tests.
📦 dev.inditex.karate.results: results generators to aggregate the cucumber results of the test scenarios, to create statistics on the karate operations usage and to copy the junit reports to the surefire folder.
📦 dev.inditex.karate.test: karate runner to run the karate tests and karate cache to share variables across tests.

It also includes the following karate resources:

📜 karate-base.js: karate base configuration
📜 karate-utils.js: karate tools utility js functions
karate-auth (basic, jwt):
- 📜 karate-auth.feature: common features to connect to authentication services.
- 📜 karate-auth.js: karate auth functions to orquestrate the authentication and authorization process.
mocks:
- 📜 mock-templates.feature: common feature to launch the mocks.
- 📜 mock-templates-functions.js: karate mocks functions to find, load, … the mock templates.
- 📜 mock-templates-inline.feature: feature to launch the mocks in inline mode.
- 📜 mock-templates-standalone.feature: feature to launch the mocks in standalone mode.

Figure 5. Karate Tools Runner Overview

karatetools-oss-starter

The karatetools-oss-starter module is a packaging module that includes the dependencies needed for a karate project to be able to use the karate tools, karatetools-oss-clients, karatetools-oss-generators and karatetools-oss-runner modules as well as any other necessary dependencies.

karatetools-oss-boot

The karatetools-oss-boot module includes the following packages:

📦 dev.inditex.karate: Spring Boot Application
📦 dev.inditex.karate.config: Spring Boot Application configuration
📦 dev.inditex.karate.controller: Spring Boot Application controllers implementing the Open API test specification and docker containers to be used as target for the karate tools tests (runner, rest, auth, jdbc, mongodb, kafka, jms, …). The controller package includes the following classes:
- BasicApiController.java: Controller implementing the Open API test specification.
- DockerHealthController.java: Controller to check the status of the docker containers.

The docker containers are defined in the docker-compose.yml file and are started automatically when the application is started.

Figure 6. Karate Tools Boot Overview

The karatetools-oss-boot module includes all the integration tests for the karate tools.

Any changes made in the Karate Tools codebase must be reflected in the corresponding integration tests in this module, both as java tests and as karate scenarios (when applicable).

Figure 7. Karate Tools Boot Integration Tests

karatetools-oss-openapi-test

The karatetools-oss-openapi-test module contains two submodules that represent the two APIs to be tested:

code/openapi-test/
├── pom.xml
├── xxx-api-rest-stable
│   ├── pom.xml
│   └── src
│       └── main
│           └── resources
│               ├── components.yml
│               └── openapi-rest.yml
└── xxx-external-api-rest-stable
    ├── pom.xml
    └── src
        └── main
            └── resources
                ├── components.yml
                └── openapi-rest.yml

Both APIs are identical, but they are used to demonstrate the testing of two different APIs (self and external APIs).

The xxx-api-rest-stable and xxx-external-api-rest-stable api structure is as follows:

karatetools-oss-karate-test

This module karatetools-oss-karate-test is a karate module to test the karate tools.

This module has been generated using the ⚙️ Karate Tools - Archetype
Includes auto-generated tests and mocks for sample api (karatetools-oss-openapi-test)
uses the karatetools-oss-starter to test the karate clients and the sample application (karatetools-oss-boot) and containers.

Any changes made in the Karate Tools codebase must be reflected in the corresponding karate tests in this module.

The structure of the module is as follows:

Figure 8. Karate Tools Test Overview

src/test/java: Java Code

e2e/karate/
├── .gitignore
├── pom.xml
└── src
    └── test
        ├── java
        │   └── com
        │       └── inditextech
        │           └── karate
        │               └── karatetools
        │                   ├── jms
        │                   │   └── JMSKarateObject.java (1)
        │                   └── test
        │                       └── KarateRunnerTest.java (2)

1	JMS Object for testing purposes
2	Java Test Runner

src/test/resources: Base and Config files

e2e/karate/
├── .gitignore
├── pom.xml
└── src
    └── test
        └── resources
            ├── config (1)
            │   ├── db
            │   │   ├── mariadb-config-local.yml
            │   │   ├── mongodb-config-local.yml
            │   │   └── postgresql-config-local.yml
            │   ├── jms
            │   │   └── activemq-config-local.yml
            │   └── kafka
            │       ├── avro
            │       │   └── karate.avsc
            │       └── kafka-config-local.yml
            ├── config-local.yml (2)
            ├── config.yml (2)
            ├── jwt (3)
            │   ├── default-jwt.yml
            │   └── invalid-jwt.yml
            ├── karate-config.js (4)
            ├── logback-test-debug.xml (5)
            ├── logback-test.xml (5)
            └── mocks (6)
                └── templates
                    └── standalone
                        └── .gitkeep

1	Karate clients config files (db, jms, kafka)
2	Configuration Files (general and environment specific)
3	Karate Authentication JWT Files (default and test specific)
4	Karate-config files
5	logback configuration files
6	karate mocks folder

src/test/resources/dev/inditex/karate: Tests related to Karate Tools features

e2e/karate/
├── .gitignore
├── pom.xml
└── src
    └── test
        └── resources
            ├── com
            │   └── inditextech
            │       └── karate
            │           ├── auth (1)
            │           │   ├── KarateAuthBackgroundScenario.feature
            │           │   ├── KarateAuthBasic.feature
            │           │   └── KarateAuthJWT.feature
            │           ├── base (2)
            │           │   └── KarateBase.feature
            │           ├── clients (3)
            │           │   ├── db (4)
            │           │   │   ├── JDBCClient-MariaDB.feature
            │           │   │   ├── JDBCClient-MariaDB.sql
            │           │   │   ├── JDBCClient-PostgreSQL.feature
            │           │   │   └── JDBCClient-PostgreSQL.sql
            │           │   ├── jms (5)
            │           │   │   └── JMSClient-ActiveMQ.feature
            │           │   ├── kafka (6)
            │           │   │   └── KafkaClients.feature
            │           │   └── mongodb (7)
            │           │       └── MongoDBClient.feature

1	Authentication tests
2	Karate Base tests
3	Karate Clients tests
4	Karate Clients tests: db
5	Karate Clients tests: jms
6	Karate Clients tests: kafka
7	Karate Clients tests: mongodb

src/test/resources/apis/dev/inditex/karate/karatetools-openapi-test/xxx-api-rest-stable: Root folder for the operation(s) feature files and validation schemas for the test api xxx-api-rest-stable

e2e/karate/
├── .gitignore
├── pom.xml
└── src
    └── test
        └── resources
            ├── apis
            │   └── com
            │       └── inditextech
            │           └── karate
            │               └── karatetools-openapi-test
            │                   └── xxx-api-rest-stable (1)
            │                       └── BasicApi (2)
            │                           ├── createItems (3)
            │                           │   ├── createItems.feature (4)
            │                           │   └── schema (5)
            │                           │       ├── createItems_201.schema.yml
            │                           │       ├── createItems_400.schema.yml
            │                           │       ├── createItems_401.schema.yml
            │                           │       └── createItems_default.schema.yml
            │                           ├── listItems (3)
            │                           │   ├── listItems.feature (4)
            │                           │   └── schema (5)
            │                           │       ├── Items_200.schema.yml
            │                           │       ├── listItems_200.schema.yml
            │                           │       ├── listItems_400.schema.yml
            │                           │       ├── listItems_401.schema.yml
            │                           │       └── listItems_default.schema.yml
            │                           └── showItemById (3)
            │                               ├── schema (5)
            │                               │   ├── showItemById_200.schema.yml
            │                               │   ├── showItemById_401.schema.yml
            │                               │   ├── showItemById_404.schema.yml
            │                               │   └── showItemById_default.schema.yml
            │                               └── showItemById.feature (4)

1	root folder for the operations
2	api tag folder
3	operation folder
4	operation feature file
5	operation validation schemas

src/test/resources/dev/inditex/karate/karatetools-openapi-test/xxx-api-rest-stable: REST Api tests

e2e/karate/
├── .gitignore
├── pom.xml
└── src
    └── test
        └── resources
            ├── com
            │   └── inditextech
            │       └── karate
            │           └── karatetools-openapi-test
            │               └── xxx-api-rest-stable (1)
            │                   ├── functional (2)
            │                   │   └── e2e (3)
            │                   │       ├── e2e.feature (4)
            │                   │       └── test-data (5)
            │                   │           ├── createItems_201.yml
            │                   │           ├── createItems_400.yml
            │                   │           ├── createItems_401.yml
            │                   │           ├── listItems_200.yml
            │                   │           ├── listItems_400.yml
            │                   │           ├── listItems_401.yml
            │                   │           ├── showItemById_200.yml
            │                   │           ├── showItemById_401.yml
            │                   │           └── showItemById_404.yml
            │                   └── smoke (6)
            │                       └── BasicApi (7)
            │                           ├── createItems (8)
            │                           │   ├── createItems.feature (4)
            │                           │   └── test-data (5)
            │                           │       ├── createItems_201.yml
            │                           │       ├── createItems_400.yml
            │                           │       └── createItems_401.yml
            │                           ├── listItems (8)
            │                           │   ├── listItems.feature (4)
            │                           │   └── test-data (5)
            │                           │       ├── listItems_200.yml
            │                           │       ├── listItems_400.yml
            │                           │       └── listItems_401.yml
            │                           └── showItemById (8)
            │                               ├── showItemById.feature (4)
            │                               └── test-data (5)
            │                                   ├── showItemById_200.yml
            │                                   ├── showItemById_401.yml
            │                                   └── showItemById_404.yml

1	root folder for the rest api test
2	root folder for the functional rest api tests
3	specific functional test folder
4	feature file
5	test data files
6	root folder for the smoke rest api tests
7	api tag folder
8	smoke tests operation folder

The tests to be executed are:

Karate Tests:
- Karate tests are used to test the karate tools in the context of a Karate project.
- These tests are executed against the test application Rest Api and the docker containers provided by the karatetools-oss-boot module.

Karate tests are required as status checks in the CI/CD pipeline pull request approval process. The level of coverage for the karate tests must reach at least the defined threshold.

Table 3. Tests Execution (Locally)
test	command	report	verification
Build app	`cd code` `mvn clean install -DskipTests -DskipITs -DskipUTs`	NA	no errors
Start app	`cd code` `APP_PORT=8888` `PROJECT_VERSION=$(mvn -q -Dexec.executable="echo" -Dexec.args='${project.version}' --non-recursive exec:exec)` `APP_PATH_TO_JAR=boot/target/karatetools-boot-$PROJECT_VERSION.jar` `APP_OPTIONS=--server.port=$APP_PORT` `java -jar "$APP_PATH_TO_JAR" "$APP_OPTIONS"`	NA	no errors
karate	`cd e2e/karate` `APP_PORT=8888` `mvn clean verify -DAPP_PORT=$APP_PORT -Dkarate.env=local -Dkarate.options="-t ~@mock.templates.inline -t ~@ignore" -Dkarate.report.options="--showLog true" -Dlogback.configurationFile=src/test/resources/logback-test-debug.xml`	`e2e/karate/target/karate-reports/karate-summary.html`	all tests pass

Table 4. Tests Execution (Github)
test	command	report	verification
karate	workflow dispatch automatically on PR	workflow execution reports	automatically on workflow execution

Table 5. Tests Execution (Locally with Code Coverage)
step	commands	expected output
Build app	`cd code` `mvn clean install -DskipTests -DskipITs -DskipUTs`	build without errors
Download JaCoCo agent and client	`cd code` `JACOCO_VERSION=$(mvn -q -Dexec.executable="echo" -Dexec.args='${jacoco.version}' --non-recursive exec:exec)` `curl -k -s -S -L -o target/jacocoagent.jar https://repo1.maven.org/maven2/org/jacoco/org.jacoco.agent/$JACOCO_VERSION/org.jacoco.agent-$JACOCO_VERSION-runtime.jar` `curl -k -s -S -L -o target/jacococli.jar https://repo1.maven.org/maven2/org/jacoco/org.jacoco.cli/$JACOCO_VERSION/org.jacoco.cli-$JACOCO_VERSION-nodeps.jar` `ls -l target/jacoco*`	JaCoCo agent and client downloaded
Start app with JaCoCo agent	`cd code` `APP_PORT=8888` `PROJECT_VERSION=$(mvn -q -Dexec.executable="echo" -Dexec.args='${project.version}' --non-recursive exec:exec)` `APP_PATH_TO_JAR=boot/target/karatetools-boot-$PROJECT_VERSION.jar` `APP_OPTIONS=--server.port=$APP_PORT` `JACOCO_AGENT_OPTIONS="-javaagent:target/jacocoagent.jar=dumponexit=true,output=file,destfile=target/jacoco-e2e/jacoco-e2e.exec,classdumpdir=target/jacoco-e2e/classes,excludes=SpringCGLIB:HibernateProxy:MessagePostProcessor:Accessor:Instantiator:.invoker.:.DTO,includes=dev.inditex."` `java "$JACOCO_AGENT_OPTIONS" -jar "$APP_PATH_TO_JAR" "$APP_OPTIONS"`	App started with JaCoCo agent
Wait for app to start	`APP_PORT=8888` `APP_HEALTH_PROBE=karatetools/health/docker` `APP_HEALTH_CHECK_URL=http://localhost:$APP_PORT/$APP_HEALTH_PROBE` `curl -s -o /dev/null -w \"%{http_code}\" $APP_HEALTH_CHECK_URL`	Status code 200
Check docker containers are up	`docker ps -a --format "table {{.ID}}\t{{.Names}}\t{{.Status}}\t{{.Image}}"`	All docker containers are up in `healthy` state
Execute Karate tests	`cd e2e/karate` `APP_PORT=8888` `mvn clean verify -DAPP_PORT=$APP_PORT -Dkarate.env=local -Dkarate.options="-t ~@mock.templates.inline -t ~@ignore" -Dkarate.report.options="--showLog true" -Dlogback.configurationFile=src/test/resources/logback-test-debug.xml`	all tests pass
Check karate report	`e2e/karate/target/karate-reports/karate-summary.html`	all tests pass
Stop app	`cd code` `CTRL-C`	App stopped
Generate JaCoCo report	`cd code` `JACOCO_CLI_REPORT_OPTIONS="target/jacoco-e2e/jacoco-e2e.exec --html target/jacoco-e2e --classfiles target/jacoco-e2e/classes --sourcefiles clients/src/main/java --sourcefiles generators/src/main/java --sourcefiles runner/src/main/java --sourcefiles boot/src/main/java"` `java -jar target/jacococli.jar report $JACOCO_CLI_REPORT_OPTIONS`	JaCoCo report generated
Check JaCoCo report	`target/jacoco-e2e/index.html`	code coverage generated by karate tests is at least 80%

karatetools-oss-docs

The documentation module karatetools-oss-docs follows standard structure for Antora documentation:

docs
├── antora-playbook-local.yml (1)
├── antora-playbook.yml (1)
├── build (2)
├── node_modules (3)
├── package-lock.json (4)
├── package.json (4)
├── src (5)
│   ├── antora.yml (6)
│   └── modules (7)
│       ├── HOME
│       ├── archetype
│       ├── clients
│       ├── configuration
│       ├── contributing
│       ├── execution
│       ├── open-api-generator
│       ├── overview
│       ├── prerequisites
│       ├── puml
│       └── release
├── supplemental-ui (8)
│   ├── css
│   ├── img
│   ├── js
│   └── partials
└── ui-bundle.zip (9)

1	Antora playbooks
2	Build folder where the output documentation is generated
3	Node modules folder
4	Node package configuration file
5	Content source root folder
6	`antora.yml` (reserved file name): Antora component version descriptor file. This file indicates to Antora that the contents of a directory named modules should be collected and processed.
7	`modules` (reserved directory name): Antora required directory located at the same hierarchical level as the antora.yml file. The modules directory must contain, at a minimum, either a ROOT module directory or a named module directory.
8	Supplemental UI to customize the UI bundle
9	Antora Default UI bundle

To locally build the documentation, you can use the following command:

# Change to the docs directory
cd docs
# Install the required dependencies
npm install
# Start the local kroki server
docker run -p8000:8000 -d yuzutech/kroki
# Build the documentation and start the local server to serve it
npm start

This command will start a local server that will serve the documentation at http://localhost:8080. If port 8080 is already in use, the server will use the next available port, such as 8081 or 8082.