### Run Asqatasun Server Docker Image

Source: https://gitlab.com/asqatasun/asqatasun/-/blob/master/docker/Asqatasun-HsqlDB-server/README.md

Starts the Asqatasun server using Docker Compose. Ensure Docker and Docker Compose are installed and prerequisites are met.

```shell
docker compose up
```

--------------------------------

### Run Asqatasun Server with UI

Source: https://gitlab.com/asqatasun/asqatasun/-/blob/master/docker/Asqatasun-MariaDB/README.md

Starts both the Asqatasun server and the web application interface using the 'with-ui' profile.

```shell
COMPOSE_PROFILES=with-ui docker compose up
```

--------------------------------

### Manage Docker Services via CLI

Source: https://context7.com/asqatasun/asqatasun/llms.txt

Commands to start, monitor, and access the Asqatasun deployment.

```bash
# Start services
docker-compose up -d

# Start with web UI
docker-compose --profile with-ui up -d

# Check logs
docker-compose logs -f server

# Access API at http://localhost:8080/api/v0/audit
# Access Web UI at http://localhost:8081
# Access Swagger docs at http://localhost:8080/swagger-ui.html
```

--------------------------------

### Get All Audits

Source: https://context7.com/asqatasun/asqatasun/llms.txt

Retrieves a list of all audits. Use this endpoint to get a general overview of audit history.

```bash
curl -X GET "http://localhost:8080/api/v0/audit"
```

--------------------------------

### Run Site Audit (Crawler) with RGAA 4.1.2

Source: https://context7.com/asqatasun/asqatasun/llms.txt

Launches a full site audit by crawling a website up to a specified depth and page limit. This example configures exclusion patterns, duration, and robots.txt compliance. The response returns the audit ID for asynchronous tracking.

```bash
curl -X POST "http://localhost:8080/api/v0/audit/site/run" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/",
    "referential": "RGAA_4_1_2",
    "level": "AA",
    "depth": 10,
    "maxPages": 1000,
    "maxDuration": 3600,
    "exclusionRegexp": "/admin/.*|/internal/.*",
    "inclusionRegexp": "",
    "robotsTxtActivation": true,
    "contractId": 1,
    "tags": ["full-site-audit", "Q4-2024"]
  }'
```

--------------------------------

### Link with Title Attribute

Source: https://gitlab.com/asqatasun/asqatasun/-/blob/master/rules/rules-creation-demo/src/test/resources/testcases/rulescreationdemo/CheckWhetherEachLinkHaventTitleAttribute/Rulescreationdemo.Test.2.1.1-2Failed-01.html

This example shows a link element that includes the 'title' attribute. This is the desired state for the rule to pass.

```html
[Link with title attribute](link1.html "title attribute present for that link")
```

--------------------------------

### Get All Contracts for a User

Source: https://context7.com/asqatasun/asqatasun/llms.txt

Retrieves all contracts associated with a specific user, identified by username. This is useful for users managing multiple projects.

```bash
curl -X GET "http://localhost:8080/api/v0/contract?username=admin"
```

--------------------------------

### GET /api/v0/audit/{id}/tests

Source: https://context7.com/asqatasun/asqatasun/llms.txt

Exports audit results in CSV format.

```APIDOC
## GET /api/v0/audit/{id}/tests

### Description
Downloads test results in CSV format organized by theme, criteria, and test with pass/fail status.

### Method
GET

### Endpoint
/api/v0/audit/{id}/tests

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the audit.

### Request Example
curl -X GET "http://localhost:8080/api/v0/audit/42/tests" -H "Accept: text/csv"
```

--------------------------------

### Get Audits by Tags

Source: https://context7.com/asqatasun/asqatasun/llms.txt

Retrieves audits filtered by specific tags. Useful for finding audits related to particular projects or timeframes.

```bash
curl -X GET "http://localhost:8080/api/v0/audit/tags/monthly-audit,production"
```

--------------------------------

### Link without Title Attribute

Source: https://gitlab.com/asqatasun/asqatasun/-/blob/master/rules/rules-creation-demo/src/test/resources/testcases/rulescreationdemo/CheckWhetherEachLinkHaventTitleAttribute/Rulescreationdemo.Test.2.1.1-2Failed-01.html

This example shows a link element that is missing the 'title' attribute. This would cause the rule to fail.

```html
[Link without title attribute](link1.html)
```

--------------------------------

### Get Contract by ID

Source: https://context7.com/asqatasun/asqatasun/llms.txt

Retrieves the details of a specific contract using its ID. Admin users can access all contracts, while regular users can only access their own.

```bash
curl -X GET "http://localhost:8080/api/v0/contract/5"
```

--------------------------------

### Run Multi-Page Audit with RGAA 4.1.2

Source: https://context7.com/asqatasun/asqatasun/llms.txt

Initiates an accessibility audit for a group of URLs using the RGAA 4.1.2 referential at the AA level. This example demonstrates disabling evidence saving and cleanup after the audit. The response returns the audit ID for asynchronous tracking.

```bash
curl -X POST "http://localhost:8080/api/v0/audit/page/run" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com/",
      "https://example.com/about",
      "https://example.com/contact"
    ],
    "referential": "RGAA_4_1_2",
    "level": "AA",
    "contractId": 1,
    "tags": ["homepage-group"],
    "saveEvidenceElements": false,
    "cleanupAfterAudit": false
  }'
```

--------------------------------

### Get Audit Status and Results

Source: https://context7.com/asqatasun/asqatasun/llms.txt

Retrieves the current status and complete results of an accessibility audit using its ID. This endpoint is intended to be polled to track the progress and completion of an asynchronous audit.

```bash
curl -X GET "http://localhost:8080/api/v0/audit/42"
```

```json
{
  "id": 42,
  "subject": {
    "id": 1,
    "type": "PAGE",
    "url": "https://example.com/",
    "nbOfPages": 1,
    "grade": "C",
    "mark": 87.5,
    "nbOfFailureOccurrences": 12,
    "repartitionBySolutionType": [
      {"type": "PASSED", "number": 45},
      {"type": "FAILED", "number": 8},
      {"type": "NEED_MORE_INFO", "number": 23},
      {"type": "NOT_APPLICABLE", "number": 30},
      {"type": "NOT_TESTED", "number": 4}
    ]
  },
  "status": "COMPLETED",
  "date": "2024-01-15T10:30:00.000Z",
  "tags": ["monthly-audit", "production"],
  "referential": "RGAA_4_1_2",
  "referentialLevel": "AA"
}
```

--------------------------------

### Configure Docker Compose for Asqatasun

Source: https://context7.com/asqatasun/asqatasun/llms.txt

Deploy the server, webapp, database, and Selenium grid using Docker Compose.

```yaml
# docker-compose.yml
version: "3.8"
services:
  db:
    image: mariadb:10.6
    environment:
      MYSQL_RANDOM_ROOT_PASSWORD: "yes"
      MYSQL_USER: asqatasun
      MYSQL_PASSWORD: securepassword123
      MYSQL_DATABASE: asqatasun
    ports:
      - "3307:3306"
    volumes:
      - asqatasun_db:/var/lib/mysql

  server:
    image: asqatasun/asqatasun-server:6.0.0
    depends_on:
      - db
      - selenium-firefox-standalone
    environment:
      JDBC_USER: asqatasun
      JDBC_PASSWORD: securepassword123
      JDBC_URL: "jdbc:mariadb://db:3306/asqatasun"
      APP_ENGINE_LOADER_SELENIUM_HUBURL: "http://selenium-firefox-standalone:4444"
      SERVER_PORT: 8080
    ports:
      - "8080:8080"

  webapp:
    image: asqatasun/asqatasun-webapp:6.0.0
    depends_on:
      - db
    environment:
      JDBC_USER: asqatasun
      JDBC_PASSWORD: securepassword123
      JDBC_URL: "jdbc:mariadb://db:3306/asqatasun"
      APP_ENGINE_LOADER_SELENIUM_HUBURL: "http://selenium-firefox-standalone:4444"
      SERVER_PORT: 8081
    ports:
      - "8081:8081"

  selenium-firefox-standalone:
    image: selenium/standalone-firefox:latest
    ports:
      - "4444:4444"

volumes:
  asqatasun_db:
```

--------------------------------

### GET /api/v0/audit

Source: https://context7.com/asqatasun/asqatasun/llms.txt

Retrieves a list of all audits or audits filtered by specific tags.

```APIDOC
## GET /api/v0/audit

### Description
Retrieves all audits or audits filtered by tags.

### Method
GET

### Endpoint
/api/v0/audit
/api/v0/audit/tags/{tags}

### Parameters
#### Path Parameters
- **tags** (string) - Optional - Comma-separated list of tags to filter audits.
```

--------------------------------

### Test Asqatasun Locally with Docker

Source: https://gitlab.com/asqatasun/asqatasun/-/blob/master/CONTRIBUTING.md

Build and run the Asqatasun application locally using Docker. This command mounts your current directory as the source and uses a specific Docker image for local development. Access the application at http://localhost:8085/asqatasun/.

```shell
./docker/build_and_run-with-docker.sh  --source-dir $(pwd) --docker-dir docker/SNAPSHOT-local
```

--------------------------------

### Shell Script for Docker Build and Run

Source: https://gitlab.com/asqatasun/asqatasun/-/blob/master/CHANGELOG.md

This script is used for building and running Asqatasun with Docker. It has been enhanced in version 4.0.2.

```shell
docker/build_and_run-with-docker.sh
```

--------------------------------

### Create Contract

Source: https://context7.com/asqatasun/asqatasun/llms.txt

Creates a new contract, which defines user permissions, allowed referentials, and audit functionalities for a project. Requires specifying user ID, project details, functionalities, options, and referentials.

```bash
curl -X PUT "http://localhost:8080/api/v0/contract" \
  -H "Content-Type: application/json" \
  -d '{ \
    "userId": 1, \
    "label": "My Website Accessibility Project", \
    "beginDate": "2024-01-01T00:00:00.000Z", \
    "endDate": "2024-12-31T23:59:59.000Z", \
    "functionalities": ["PAGES", "DOMAIN", "SCENARIO", "UPLOAD"], \
    "options": { \
      "DOMAIN": "https://example.com/", \
      "MAX_DOCUMENTS": "500", \
      "DEPTH": "15", \
      "MAX_DURATION": "7200" \
    }, \
    "referentials": ["RGAA_4_1_2", "RGAA_4_0", "SEO"] \
  }'
```

--------------------------------

### Push Changes to Personal Repository

Source: https://gitlab.com/asqatasun/asqatasun/-/blob/master/CONTRIBUTING.md

After making changes and committing them, push your feature branch to your personal fork of the Asqatasun repository. Replace `<id-of-issue>` with the actual issue number.

```shell
git push origin <id-of-issue>-fix
     # git push origin 115-fix
```

--------------------------------

### Shell Script for Tagging Releases

Source: https://gitlab.com/asqatasun/asqatasun/-/blob/master/CHANGELOG.md

This script is used for tagging new releases in Asqatasun. In version 4.0.2, it was updated to use the '--push' option for pushing new tags.

```shell
release/bump_asqatasun.sh : use --push option for pushing new tag
```

--------------------------------

### Define CSS utility classes for sizing and accessibility

Source: https://gitlab.com/asqatasun/asqatasun/-/blob/master/engine/scenarioloader/src/test/resources/testpages/visibility-test-zero-bbox.html

Use .zero-size to hide elements by setting dimensions to zero, and .sr-only to visually hide content while keeping it accessible to screen readers.

```css
.zero-size { width: 0; height: 0; overflow: hidden; } .sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); border: 0; }
```

--------------------------------

### GET /api/v0/audit/{auditId}

Source: https://context7.com/asqatasun/asqatasun/llms.txt

Retrieves the current status and complete results of an audit by its ID. Poll this endpoint to track audit progress.

```APIDOC
## GET /api/v0/audit/{auditId}

### Description
Retrieves the current status and complete results of an audit by its ID. Poll this endpoint to track audit progress.

### Method
GET

### Endpoint
/api/v0/audit/{auditId}

### Parameters
#### Path Parameters
- **auditId** (integer) - Required - The ID of the audit to retrieve.

### Response
#### Success Response (200)
- **id** (integer) - The audit ID.
- **subject** (object) - Information about the audited subject.
  - **id** (integer) - The subject ID.
  - **type** (string) - The type of subject (e.g., "PAGE").
  - **url** (string) - The URL audited.
  - **nbOfPages** (integer) - The number of pages audited.
  - **grade** (string) - The overall grade (e.g., "C").
  - **mark** (number) - The accessibility score.
  - **nbOfFailureOccurrences** (integer) - The number of failure occurrences.
  - **repartitionBySolutionType** (array of objects) - Distribution of results by type.
    - **type** (string) - The result type (e.g., "PASSED", "FAILED").
    - **number** (integer) - The count for this result type.
- **status** (string) - The current status of the audit (e.g., "COMPLETED").
- **date** (string) - The date and time the audit was completed or started.
- **tags** (array of strings) - Tags associated with the audit.
- **referential** (string) - The accessibility referential used.
- **referentialLevel** (string) - The accessibility level used.

#### Response Example
```json
{
  "id": 42,
  "subject": {
    "id": 1,
    "type": "PAGE",
    "url": "https://example.com/",
    "nbOfPages": 1,
    "grade": "C",
    "mark": 87.5,
    "nbOfFailureOccurrences": 12,
    "repartitionBySolutionType": [
      {"type": "PASSED", "number": 45},
      {"type": "FAILED", "number": 8},
      {"type": "NEED_MORE_INFO", "number": 23},
      {"type": "NOT_APPLICABLE", "number": 30},
      {"type": "NOT_TESTED", "number": 4}
    ]
  },
  "status": "COMPLETED",
  "date": "2024-01-15T10:30:00.000Z",
  "tags": ["monthly-audit", "production"],
  "referential": "RGAA_4_1_2",
  "referentialLevel": "AA"
}
```
```

--------------------------------

### Clone and Branch for Local Development

Source: https://gitlab.com/asqatasun/asqatasun/-/blob/master/CONTRIBUTING.md

Clone your forked repository and create a new branch for your fixes or features, based on the master branch. Replace `<id-of-issue>` with the actual issue number.

```shell
git clone https://gitlab.com/<user>/Asqatasun.git
     # instead of:   git clone https://gitlab.com/asqatasun/Asqatasun.git
cd Asqatasun
git checkout -b <id-of-issue>-fix
     # git checkout -b 115-fix
```

--------------------------------

### Write Rule Unit Tests in Java

Source: https://context7.com/asqatasun/asqatasun/llms.txt

Extend AbstractRuleImplementationTestCase to verify rule logic against HTML test cases.

```java
import org.asqatasun.entity.audit.TestSolution;
import org.asqatasun.rules.test.AbstractRuleImplementationTestCase;

public class MyCustomRule010101Test extends AbstractRuleImplementationTestCase {

    public MyCustomRule010101Test(String testName) {
        super(testName);
    }

    @Override
    protected void setUpRuleImplementationClassName() {
        setRuleImplementationClassName(
            "com.example.rules.MyCustomRule010101"
        );
    }

    @Override
    protected void setUpWebResourceMap() {
        // Test case: Page with images missing alt
        addWebResource("MyCustomRule-010101-1Passed-01",
            "<html><body><img src='test.jpg' alt='Test image'/></body></html>");

        addWebResource("MyCustomRule-010101-1Failed-01",
            "<html><body><img src='test.jpg'/></body></html>");

        addWebResource("MyCustomRule-010101-1NMI-01",
            "<html><body><img src='test.jpg' alt=''/></body></html>");
    }

    @Override
    protected void setProcess() {
        // Verify passed case
        checkResultIsPassed(
            processPageTest("MyCustomRule-010101-1Passed-01"),
            0  // Expected number of remarks
        );

        // Verify failed case
        checkResultIsFailed(
            processPageTest("MyCustomRule-010101-1Failed-01"),
            1,  // Expected failures
            "ImageWithoutAltAttribute"  // Expected message key
        );

        // Verify needs more info case
        checkResultIsPreQualified(
            processPageTest("MyCustomRule-010101-1NMI-01"),
            1,
            "EmptyAltAttribute"
        );
    }
}
```

--------------------------------

### Override Docker Compose Variables

Source: https://gitlab.com/asqatasun/asqatasun/-/blob/master/docker/Asqatasun-HsqlDB-server/README.md

Locally overrides variables defined in Docker Compose, such as changing the MariaDB host port. This example sets the MariaDB host port to 3307.

```shell
DB_HOST_PORT=3307 docker compose up
```

--------------------------------

### Run Scenario Audit with Selenium IDE JSON

Source: https://context7.com/asqatasun/asqatasun/llms.txt

Executes an accessibility audit based on a Selenium IDE scenario. The scenario is provided as a JSON string, enabling testing of complex user workflows. The response returns the audit ID for asynchronous tracking.

```bash
curl -X POST "http://localhost:8080/api/v0/audit/scenario/run" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Login Flow Test",
    "scenario": "{\"id\":\"39429fc5-89ab-4270-bb0f-640c5c9390b3\",\"version\":\"2.0\",\"name\":\"Login Test\",\"url\":\"https://example.com\",\"tests\":[{\"id\":\"9d3869a0-60ac-4a1b-bd3f-0f0f65f302d4\",\"name\":\"Open login page\",\"commands\":[{\"id\":\"48d5b89b-1421-416e-a029-bb1c208221ef\",\"command\":\"open\",\"target\":\"/login\",\"value\":\"\"}]}],\"suites\":[{\"id\":\"34095dff-101a-4db9-a045-bbfe6a7c9c44\",\"name\":\"Login Suite\",\"persistSession\":false,\"parallel\":false,\"timeout\":300,\"tests\":[\"9d3869a0-60ac-4a1b-bd3f-0f0f65f302d4\"]}],\"urls\":[\"https://example.com/\"],\"plugins\":[]}",
    "referential": "RGAA_4_1_2",
    "level": "AA",
    "contractId": 1,
    "tags": ["scenario-test", "login-flow"]
  }'
```

--------------------------------

### POST /api/v0/audit/site/run

Source: https://context7.com/asqatasun/asqatasun/llms.txt

Launches a full site audit that crawls the website up to a specified depth and maximum number of pages. Supports URL inclusion/exclusion patterns and robots.txt compliance.

```APIDOC
## POST /api/v0/audit/site/run

### Description
Launches a full site audit that crawls the website up to a specified depth and maximum number of pages. Supports URL inclusion/exclusion patterns and robots.txt compliance.

### Method
POST

### Endpoint
/api/v0/audit/site/run

### Parameters
#### Request Body
- **url** (string) - Required - The starting URL for the site crawl.
- **referential** (string) - Required - The accessibility referential to use (e.g., "RGAA_4_1_2").
- **level** (string) - Required - The accessibility level to audit against (e.g., "AA").
- **depth** (integer) - Optional - The maximum crawl depth (defaults to 10).
- **maxPages** (integer) - Optional - The maximum number of pages to crawl (defaults to 1000).
- **maxDuration** (integer) - Optional - The maximum duration of the crawl in seconds (defaults to 3600).
- **exclusionRegexp** (string) - Optional - A regular expression to exclude URLs.
- **inclusionRegexp** (string) - Optional - A regular expression to include URLs.
- **robotsTxtActivation** (boolean) - Optional - Whether to respect robots.txt (defaults to true).
- **contractId** (integer) - Required - The ID of the contract associated with the audit.
- **tags** (array of strings) - Optional - Tags to associate with the audit.

### Request Example
```json
{
  "url": "https://example.com/",
  "referential": "RGAA_4_1_2",
  "level": "AA",
  "depth": 10,
  "maxPages": 1000,
  "maxDuration": 3600,
  "exclusionRegexp": "/admin/.*|/internal/.*",
  "inclusionRegexp": "",
  "robotsTxtActivation": true,
  "contractId": 1,
  "tags": ["full-site-audit", "Q4-2024"]
}
```

### Response
#### Success Response (200)
- **auditId** (integer) - The ID of the initiated audit.

#### Response Example
```
57
```
```

--------------------------------

### Create Custom Accessibility Rules

Source: https://context7.com/asqatasun/asqatasun/llms.txt

Extend AbstractDetectionPageRuleImplementation to define custom rules using CSS-like selectors and test solutions.

```java
import org.apache.commons.lang3.tuple.ImmutablePair;
import org.asqatasun.entity.audit.TestSolution;
import org.asqatasun.ruleimplementation.AbstractDetectionPageRuleImplementation;
import org.asqatasun.rules.elementselector.SimpleElementSelector;

import static org.asqatasun.rules.keystore.AttributeStore.*;
import static org.asqatasun.rules.keystore.CssLikeQueryStore.*;
import static org.asqatasun.rules.keystore.RemarkMessageStore.*;

/**
 * Rule: All images must have an alt attribute
 * Tests for presence of alt attribute on img elements
 */
public class MyCustomRule010101 extends AbstractDetectionPageRuleImplementation {

    public MyCustomRule010101() {
        super(
            // CSS selector to find elements
            new SimpleElementSelector("img:not([alt])"),

            // Solution when matching elements ARE found (missing alt = failure)
            new ImmutablePair<>(TestSolution.FAILED, "ImageWithoutAltAttribute"),

            // Solution when NO matching elements found (all have alt = passed)
            new ImmutablePair<>(TestSolution.PASSED, ""),

            // Evidence element attributes to include in report
            SRC_ATTR
        );
    }
}
```

--------------------------------

### POST /api/v0/audit/scenario/run

Source: https://context7.com/asqatasun/asqatasun/llms.txt

Executes an accessibility audit on a Selenium IDE scenario, enabling testing of dynamic content and user workflows like login forms and checkout processes.

```APIDOC
## POST /api/v0/audit/scenario/run

### Description
Executes an accessibility audit on a Selenium IDE scenario, enabling testing of dynamic content and user workflows like login forms and checkout processes.

### Method
POST

### Endpoint
/api/v0/audit/scenario/run

### Parameters
#### Request Body
- **name** (string) - Required - The name of the scenario audit.
- **scenario** (string) - Required - The Selenium IDE scenario definition in JSON format.
- **referential** (string) - Required - The accessibility referential to use (e.g., "RGAA_4_1_2").
- **level** (string) - Required - The accessibility level to audit against (e.g., "AA").
- **contractId** (integer) - Required - The ID of the contract associated with the audit.
- **tags** (array of strings) - Optional - Tags to associate with the audit.

### Request Example
```json
{
  "name": "Login Flow Test",
  "scenario": "{\"id\":\"39429fc5-89ab-4270-bb0f-640c5c9390b3\",\"version\":\"2.0\",\"name\":\"Login Test\",\"url\":\"https://example.com\",\"tests\":[{\"id\":\"9d3869a0-60ac-4a1b-bd3f-0f0f65f302d4\",\"name\":\"Open login page\",\"commands\":[{\"id\":\"48d5b89b-1421-416e-a029-bb1c208221ef\",\"command\":\"open\",\"target\":\"/login\",\"value\":\"\"}]}],\"suites\":[{\"id\":\"34095dff-101a-4db9-a045-bbfe6a7c9c44\",\"name\":\"Login Suite\",\"persistSession\":false,\"parallel\":false,\"timeout\":300,\"tests\":[\"9d3869a0-60ac-4a1b-bd3f-0f0f65f302d4\"]}],\"urls\":[\"https://example.com/\"],\"plugins\":[]}",
  "referential": "RGAA_4_1_2",
  "level": "AA",
  "contractId": 1,
  "tags": ["scenario-test", "login-flow"]
}
```
```

--------------------------------

### POST /api/v0/audit/page/run

Source: https://context7.com/asqatasun/asqatasun/llms.txt

Initiates an accessibility audit on one or more specified URLs against the chosen referential and level. Returns the audit ID immediately while the audit runs asynchronously.

```APIDOC
## POST /api/v0/audit/page/run

### Description
Initiates an accessibility audit on one or more specified URLs against the chosen referential and level. Returns the audit ID immediately while the audit runs asynchronously.

### Method
POST

### Endpoint
/api/v0/audit/page/run

### Parameters
#### Request Body
- **urls** (array of strings) - Required - A list of URLs to audit.
- **referential** (string) - Required - The accessibility referential to use (e.g., "RGAA_4_1_2").
- **level** (string) - Required - The accessibility level to audit against (e.g., "AA").
- **contractId** (integer) - Required - The ID of the contract associated with the audit.
- **tags** (array of strings) - Optional - Tags to associate with the audit.
- **saveEvidenceElements** (boolean) - Optional - Whether to save evidence elements (defaults to true).
- **cleanupAfterAudit** (boolean) - Optional - Whether to clean up after the audit (defaults to true).

### Request Example
```json
{
  "urls": ["https://example.com/"],
  "referential": "RGAA_4_1_2",
  "level": "AA",
  "contractId": 1,
  "tags": ["monthly-audit", "production"]
}
```

### Response
#### Success Response (200)
- **auditId** (integer) - The ID of the initiated audit.

#### Response Example
```
42
```
```

--------------------------------

### Implement AuditServiceListener for Callbacks

Source: https://context7.com/asqatasun/asqatasun/llms.txt

Implement the AuditServiceListener interface to handle audit completion and failure events. Register the listener with the AuditService before initiating an audit.

```java
import org.asqatasun.service.AuditServiceListener;
import org.asqatasun.entity.audit.Audit;

public class MyAuditListener implements AuditServiceListener {

    private final Long auditId;

    public MyAuditListener(Long auditId) {
        this.auditId = auditId;
    }

    @Override
    public Long getAuditId() {
        return auditId;
    }

    @Override
    public void auditCompleted(Audit audit) {
        System.out.println("Audit " + audit.getId() + " completed!");
        System.out.println("Status: " + audit.getStatus());
        System.out.println("Results count: " + audit.getNetResultList().size());

        // Process results
        audit.getNetResultList().forEach(result -> {
            System.out.println("Test: " + result.getTest().getLabel() +
                             " - Result: " + result.getValue());
        });
    }

    @Override
    public void auditCrashed(Audit audit, Exception exception) {
        System.err.println("Audit " + audit.getId() + " failed: " +
                          exception.getMessage());
    }
}

// Register listener before audit
auditService.add(new MyAuditListener(expectedAuditId));
Audit audit = auditService.auditPage(url, params, tags);
```

--------------------------------

### Define Data Models in Kotlin

Source: https://context7.com/asqatasun/asqatasun/llms.txt

Enums for accessibility referentials and conformance levels, plus a grading function.

```kotlin
// Available referentials
enum class Referential(val code: String) {
    RGAA_4_0("Rgaa40"),      // French RGAA 4.0
    RGAA_4_1_2("Rgaa412"),   // French RGAA 4.1.2 (default)
    SEO("Seo")               // SEO rules
}

// Conformance levels (WCAG-based)
enum class Level(val code: String) {
    AAA("Or"),   // Gold - highest conformance
    AA("Ar"),    // Silver - standard conformance (default)
    A("Bz")      // Bronze - minimum conformance
}

// Grade calculation based on accessibility score
fun computeGrade(mark: Float): GradeResult = when {
    mark == 100f -> GradeResult.A  // Perfect score
    mark > 90f -> GradeResult.B    // Excellent
    mark > 85f -> GradeResult.C    // Good
    mark > 75f -> GradeResult.D    // Moderate
    mark > 60f -> GradeResult.E    // Poor
    else -> GradeResult.F          // Very Poor
}
```

--------------------------------

### Run Single Page Audit with RGAA 4.1.2

Source: https://context7.com/asqatasun/asqatasun/llms.txt

Initiates an accessibility audit for a single URL using the RGAA 4.1.2 referential at the AA level. The request includes contract ID and custom tags. The response returns the audit ID for asynchronous tracking.

```bash
curl -X POST "http://localhost:8080/api/v0/audit/page/run" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/"],
    "referential": "RGAA_4_1_2",
    "level": "AA",
    "contractId": 1,
    "tags": ["monthly-audit", "production"]
  }'
```

--------------------------------

### Run Hurl API tests

Source: https://gitlab.com/asqatasun/asqatasun/-/blob/master/testing-tools/E2E-testing-server/README.md

Executes the Hurl test suite with environment variables for timestamps and authentication credentials.

```shell
cd server/asqatasun-server/src/test/Hurl/

export HURL_now=$(date '+%Y-%m-%dT%H:%M:%S')
export HURL_later=$(date '+%Y-%m-%dT%H:%M:%S' -d"+1year")
hurl \
  --variables-file hurl-options.env \
  --user admin@asqatasun.org:myAsqaPassword \
  --verbose \
  --report-html ./Report/ \
  --test Testsuite/*
```

--------------------------------

### HTML Form Error Handling

Source: https://gitlab.com/asqatasun/asqatasun/-/blob/master/CHANGELOG.md

This snippet shows how to display errors for a form field named 'scenarioFile' in an HTML form. It allows for `<abbr>` tags within the error message.

```html
<form:errors path="scenarioFile">
```

--------------------------------

### Export Audit Results as CSV

Source: https://context7.com/asqatasun/asqatasun/llms.txt

Downloads audit test results in CSV format. The output is organized by theme, criteria, and test, including pass/fail status for each audited URL.

```bash
curl -X GET "http://localhost:8080/api/v0/audit/42/tests" \
  -H "Accept: text/csv" \
  -o results.csv
```

```text
# CSV Output:
# "Theme","Criteria","Test","https://example.com/"
# 1,1,1,pq    # pq = pre-qualified (needs manual review)
# 1,1,2,c     # c = compliant (passed)
# 1,1,3,nc    # nc = non-compliant (failed)
# 1,2,1,na    # na = not applicable
# 9,1,1,c
# 1,3,9,nt    # nt = not tested
```

--------------------------------

### Run Single Page Audit

Source: https://context7.com/asqatasun/asqatasun/llms.txt

Executes an accessibility audit for a single URL. Requires specifying the URL and a list of tags for organization. Parameters are fetched for RGAA 4.1.2 at AA level.

```java
import org.asqatasun.service.AuditService;
import org.asqatasun.entity.audit.Audit;
import org.asqatasun.entity.audit.Tag;
import org.asqatasun.entity.parameterization.Parameter;
import java.util.Set;
import java.util.List;

@Service
public class MyAccessibilityService {

    private final AuditService auditService;
    private final ParameterDataService parameterDataService;

    @Autowired
    public MyAccessibilityService(AuditService auditService,
                                   ParameterDataService parameterDataService) {
        this.auditService = auditService;
        this.parameterDataService = parameterDataService;
    }

    public Audit runSinglePageAudit(String url, List<Tag> tags) {
        // Get parameters for RGAA 4.1.2 at AA level
        Set<Parameter> params = parameterDataService
            .getParameterSetFromAuditLevel("Rgaa412", "Ar");

        return auditService.auditPage(url, params, tags);
    }

    public Audit runSiteAudit(String siteUrl, List<Tag> tags) {
        Set<Parameter> params = parameterDataService
            .getParameterSetFromAuditLevel("Rgaa412", "Ar");

        return auditService.auditSite(siteUrl, params, tags);
    }

    public Audit runGroupOfPagesAudit(String siteName,
                                       List<String> pageUrls,
                                       List<Tag> tags) {
        Set<Parameter> params = parameterDataService
            .getParameterSetFromAuditLevel("Rgaa412", "Ar");

        return auditService.auditSite(siteName, pageUrls, params, tags);
    }

    public Audit runScenarioAudit(String scenarioName,
                                   String scenarioContent,
                                   List<Tag> tags) {
        Set<Parameter> params = parameterDataService
            .getParameterSetFromAuditLevel("Rgaa412", "Ar");

        return auditService.auditScenario(scenarioName, scenarioContent, params, tags);
    }
}
```

--------------------------------

### CSV Export Mapping in Java

Source: https://context7.com/asqatasun/asqatasun/llms.txt

Provides a mapping for CSV export codes to test result types. Useful for understanding exported data.

```java
// c  = compliant (PASSED)
// nc = non-compliant (FAILED)
// pq = pre-qualified (NEED_MORE_INFO, DETECTED, SUSPECTED_*)
// na = not applicable
// nt = not tested
```