robotframework-xmlvalidator 1.0.0__tar.gz → 2.0.0__tar.gz

{robotframework_xmlvalidator-1.0.0 → robotframework_xmlvalidator-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: robotframework-xmlvalidator
-Version: 1.0.0
+Version: 2.0.0
 Summary: A Robot Framework test library for validating XML files against XSD schemas
 License: Apache-2.0
 Keywords: robotframework,xml,xsd,validation,test-library,test,testing,test-automation
@@ -25,9 +25,14 @@ Project-URL: Homepage, https://github.com/MichaelHallik/robotframework-xmlvalida
 Project-URL: Repository, https://github.com/MichaelHallik/robotframework-xmlvalidator
 Description-Content-Type: text/markdown
 
-[![PyPI version](https://img.shields.io/pypi/v/robotframework-xmlvalidator.svg)](https://pypi.org/project/robotframework-xmlvalidator/)
-[![License](https://img.shields.io/pypi/l/robotframework-xmlvalidator)](LICENSE)
-[![Tests](https://github.com/MichaelHallik/robotframework-xmlvalidator/actions/workflows/test.yml/badge.svg)](https://github.com/MichaelHallik/robotframework-xmlvalidator/actions/workflows/test.yml)
+| Version | License | Tests |
+|---------|---------|-------|
+| [![PyPI version](https://img.shields.io/pypi/v/robotframework-xmlvalidator.svg)](https://pypi.org/project/robotframework-xmlvalidator/) | [![License](https://img.shields.io/pypi/l/robotframework-xmlvalidator?cacheSeconds=600)](LICENSE) | [![Tests](https://github.com/MichaelHallik/robotframework-xmlvalidator/actions/workflows/test.yml/badge.svg)](https://github.com/MichaelHallik/robotframework-xmlvalidator/actions/workflows/test.yml) |
+
+| Downloads | Update Badge |
+|-----------|---------------|
+| [![Total Downloads](https://github.com/MichaelHallik/robotframework-xmlvalidator/raw/main/badge_pepy_downloads.svg)](https://pepy.tech/project/robotframework-xmlvalidator) | [![Run Badge Update](https://github.com/MichaelHallik/robotframework-xmlvalidator/actions/workflows/update_pepy_badge.yml/badge.svg)](https://github.com/MichaelHallik/robotframework-xmlvalidator/actions/workflows/update_pepy_badge.yml) |
+
 
 <details>
 <summary><strong>📚 Table of Contents</strong></summary>
@@ -46,14 +51,26 @@ Description-Content-Type: text/markdown
     - [Examples](#examples)
       - [Using a preloaded schema](#using-a-preloaded-schema)
       - [Defer schema loading to the test case(s)](#defer-schema-loading-to-the-test-cases)
-      - [Importing with preloaded XSD that requires a base\_url](#importing-with-preloaded-xsd-that-requires-a-base_url)
-      - [Importing with custom error\_facets](#importing-with-custom-error_facets)
+      - [Importing with preloaded XSD that requires a `base_url`](#importing-with-preloaded-xsd-that-requires-a-base_url)
+      - [Importing with custom `error_facets`](#importing-with-custom-error_facets)
+      - [Importing with \`fail\_on\_errors=True](#importing-with-fail_on_errorstrue)
       - [Further examples](#further-examples)
   - [Using the library](#using-the-library)
     - [Keyword overview](#keyword-overview)
+      - [Error collection](#error-collection)
+      - [Batch mode](#batch-mode)
+      - [Single file mode](#single-file-mode)
+      - [Test case status - fail\_on\_error](#test-case-status---fail_on_error)
+      - [Dyanmic XSD resolution](#dyanmic-xsd-resolution)
+    - [Error collection](#error-collection-1)
+      - [XSD Schema violations.](#xsd-schema-violations)
+      - [Malformed XML](#malformed-xml)
+      - [File-level issues](#file-level-issues)
+      - [Final note on error collection](#final-note-on-error-collection)
     - [Keyword documentation](#keyword-documentation)
     - [Keyword example usage](#keyword-example-usage)
       - [A few basic examples](#a-few-basic-examples)
+      - [Demo test suite file as examples](#demo-test-suite-file-as-examples)
       - [Integration tests as examples](#integration-tests-as-examples)
     - [Example console output](#example-console-output)
     - [Example CSV output](#example-csv-output)
@@ -75,6 +92,8 @@ Description-Content-Type: text/markdown
     - [Continuous Integration \& GitHub templates](#continuous-integration--github-templates)
   - [Class architecture (Simplified)](#class-architecture-simplified)
   - [Project Structure](#project-structure)
+  - [Changelog](#changelog)
+  - [Roadmap](#roadmap)
   - [License](#license)
   - [Author](#author)
 
@@ -99,7 +118,7 @@ It provides structured and detailed reporting of XML parse errors (malformed XML
 - Customizable error attributes (`path`, `reason`, `message`, etc.)
 - Batch validation and per-file error tracking
 - Export collected errors to CSV (with optional file name timestamping).
-- And more (see below and the keyword documentation).
+- And more.
 
 ---
 
@@ -147,11 +166,12 @@ See the [Robot Framework Library Scope docs](https://robotframework.org/robotfra
 
 ### Library arguments
 
-| Argument       | Type        | Required? | Description                                                                        |
-|----------------|-------------|-----------|------------------------------------------------------------------------------------|
-| `xsd_path`     | `str`       | No        | Path to an XSD file or folder to preload during initialization. In case of a folder, the folder must hold one file only.                                                                                                             |
-| `base_url`     | `str`       | No        | Base path used to resolve includes/imports within the provided XSD schema.         |
-| `error_facets` | `list[str]` | No        | The attributes of validation errors to collect and report (e.g., `path`, `reason`) |
+| Argument        | Type        | Required? | Description                                                                                                            | Default         |
+|-----------------|-------------|-----------|------------------------------------------------------------------------------------------------------------------------|-----------------|
+| `xsd_path`      | `str`       | No        | Path to an XSD file/folder to preload during initialization. In case of a folder, the folder must hold one file only.  | None            |
+| `base_url`      | `str`       | No        | Base path used to resolve includes/imports within the provided XSD schema.                                             | None            |
+| `error_facets`  | `list[str]` | No        | The attributes of validation errors to collect and report (e.g., `path`, `reason`)                                     | [path, reason]  |
+| `fail_on_error` | `bool`      | No        | Whether to fail the test case if one or more XML validation errors are found. Can be overridden per keyword call.      | True            |
 
 ### Examples
 
@@ -168,7 +188,7 @@ Library    xmlvalidator    xsd_path=path/to/schema.xsd
 Library    xmlvalidator
 ```
 
-#### Importing with preloaded XSD that requires a base_url
+#### Importing with preloaded XSD that requires a `base_url`
 
 ```robotframework
 Library    xmlvalidator    xsd_path=path/to/schema_with_include.xsd
@@ -177,7 +197,7 @@ Library    xmlvalidator    xsd_path=path/to/schema_with_include.xsd
 
 Use `base_url` when your XSD uses `<xs:include>` or `<xs:import>` with relative paths.
 
-#### Importing with custom error_facets
+#### Importing with custom `error_facets`
 
 Use the `error_facets` argument to control which attributes of detected errors will be collected and reported.
 
@@ -196,6 +216,21 @@ Library    xmlvalidator    xsd_path=schemas/schema.xsd
 ...                        error_facets=value, namespaces
 ```
 
+#### Importing with `fail_on_errors=True
+
+The fail_on_errors argument controls whether a test case should fail if XML validation errors are detected.
+
+It defaults to True.
+
+The library's batch validation behavior remains unchanged. That is, `fail_on_errors=True` does *not* short-circuit the validation process in any way.
+
+Set `fail_on_errors=False` to log validation issues without failing the test. This is useful for:
+
+- Non-blocking checks in dashboards or QA reports.
+- Legacy or transitional systems where some invalid files are expected.
+- Schema discovery or diagnostics, where conformance isn’t yet enforced.
+- Soft rollout of stricter validation rules, allowing time to adapt.
+
 #### Further examples
 
 See also the [library initialization Robot test file](test/integration/01_library_initialization.robot).
@@ -206,43 +241,154 @@ See also the [library initialization Robot test file](test/integration/01_librar
 
 ### Keyword overview
 
-| Keyword                  | Description |
-|--------------------------|-------------|
+Thi section merely provides a short summary of the library's capabilities.
+
+For more details, please see the [keyword documentation](https://michaelhallik.github.io/robotframework-xmlvalidator/XmlValidator.html).
+
+| Keyword                  | Description                                                         |
+|--------------------------|---------------------------------------------------------------------|
 | `Validate Xml Files`     | Validate one or more XML files against one or more XSD schema files |
-| `Reset Schema`           | Clear the currently loaded XSD schema |
-| `Reset Errors`           | Clear the set of collected errors |
-| `Get Schema`             | Get the current schema name or object |
-| `Log Schema`             | Log the currently loaded schema |
-| `Get Error Facets`       | Returns a list of the currently active error facets |
-| `Reset Error Facets`     | Reset the error facets to default (`path`, `reason`) |
+| `Reset Schema`           | Clear the currently loaded XSD schema                               |
+| `Reset Errors`           | Clear the set of collected errors                                   |
+| `Get Schema`             | Get the current schema name or object                               |
+| `Log Schema`             | Log the currently loaded schema                                     |
+| `Get Error Facets`       | Returns a list of the currently active error facets                 |
+| `Reset Error Facets`     | Reset the error facets to default (`path`, `reason`)                |
 
 The main keyword is `Validate Xml Files`. The other keywords are convenience/helper functions, e.g. 'Reset Error Facets'.
 
+#### Error collection
+
 The `Validate Xml Files` validates one or more XML files against one or more XSD schema files and collects and reports all encountered errors.
 
-The type of error that the keyword can detect is not limited to XSD violations, but may also pertain to malformed XML files (e.g. parse errors), empty files, unmatched XML files (no XSD match found), etc.
+The type of error that the keyword can detect is not limited to XSD violations, but may also pertain to malformed XML files, empty files, unmatched XML files (no XSD match found), etc.
 
 Errors that result from malformed XML files or from XSD violations support detailed error reporting. Using the `error_facets` argument you may specify the details the keyword should collect and report about captured errors.
 
-When operating in batch mode, the `Validate Xml Files` keyword always validates the entire set of passed XML files.
+#### Batch mode
+
+The `Validate Xml Files` keyword always validates the entire set of passed XML files.
 
-That is, when it encounters an error in a file, it does not fail. Rather, it collects the error details (as determined by the `error_facets` arg) and then continues validating the current file as well as any subsequent file(s).
+That is, when it encounters an error in a file, it does not fail and stop execution. Rather, it collects the error details (as determined by the `error_facets` arg) and then continues validating the current file as well as any subsequent file(s).
 
 In that fashion the keyword works through the entire set of files.
 
-When having finished checking the last file, it will log a summary of the test run and then proceed to report all collected errors in the console, in the RF log and, optionally, in the form of a CSV file.
+Once *all* files are processed it will log a summary of the test run and then proceed to report all collected errors in the console, in the RF log and, optionally, in the form of a CSV file.
 
-However, in case you want your test case to fail when one or more errors have been detected, you can use the ``fail_on_errors`` (bool) argument to make it so. It defaults to False. When setting it to True, then the keyword will still check each XML file (and collect possible errors), but after it has thus processed the batch, it will fail if one or more errors will have been detected.
+For example:
+- If you validate fifteen XML files and five of them contain schema violations or other errors, all files will still be processed.
+- Errors are simply collected throughout the run and reported collectively, only after the final file has been (fully) processed.
+- The test case will fail (assuming `fail_on_errors=True`) only after all files have been checked, ensuring comprehensive diagnostics.
 
-The keyword further supports the dynamic matching (i.e. pairing) of XML and XSD files, using either a 'by filename' or a 'by namespace' strategy. That means you can simply pass the paths to a folder containing XML files and to a folder containing XSD files and the keyword will determine which XSD schema file to use for each XML file. If the XML and XSD files reside in the same folder, you only have to pass one folder path. When no matching XSD schema could be identified for an XML file, this will be integrated into the mentioned summary and error reporting (the keyword will not fail).
+#### Single file mode
 
 Of course, you may also refer to specific XML/XSD files (instead of to folders). In that case, no matching will be attempted, but the keyword will simply try to validate the specified XML file against the specified XSD file.
 
-See for more details the keyword documentation.
+Actually, almost anything goes:
+
+- one folder with: one or more XML files and one or more XSD files
+- one folder with one or more XML files and another folder with one or more XSD files
+- one folder with one or more XML files and a single XSD file
+- a single XML file and a sigle XSD file
+
+#### Test case status - fail_on_error
+
+A test case that has resulted in the collection of one or more errors (of whatever type) will receive a status of FAIL. You can use the ``fail_on_errors`` (bool) argument to change this default behaviour. When set to `False`, the test cases's status will always be PASS, regardless whether errors were collected or not.
+
+#### Dyanmic XSD resolution
+
+The keyword further supports the dynamic matching (i.e. pairing) of XML and XSD files, using either a 'by filename' or a 'by namespace' strategy. That means you can simply pass the paths to a folder containing XML files and to a folder containing XSD files and the keyword will determine which XSD schema file to use for each XML file. If the XML and XSD files reside in the same folder, you only have to pass one folder path. When no matching XSD schema could be identified for an XML file, this will be integrated into the mentioned summary and error reporting (the keyword will not fail).
+
+### Error collection
+
+Errors that are collected and reported can be categorized as follows:
+
+#### XSD Schema violations.
+
+- Missing or extra elements that violate cardinality rules, e.g.:
+  - Verifies that all mandatory elements (minOccurs > 0) are present in the XML.
+  - Ensures that optional elements (minOccurs = 0) do not exceed their maximum allowed occurrences (maxOccurs).
+
+- Sequence and order violations:
+  - Validates the order of child elements within a parent element if the schema specifies a sequence model (`<xsd:sequence>`).
+  - Detects elements that are out of order or missing in a sequence.
+
+- Datatype violations:
+  - Ensures that element and attribute values conform to their specified datatypes (e.g., xs:string, xs:integer, xs:dateTime).
+  - Identifies invalid formats, such as incorrect date or time formats for xs:date and xs:dateTime.
+
+- Pattern and enumeration violations:
+  - Checks that values conform to patterns defined using `<xsd:pattern>`.
+  - Ensures that values fall within allowed enumerations specified in the schema.
+
+- Attribute validation:
+  - Verifies that required attributes are present.
+  - Ensures that attribute values adhere to their declared datatypes and constraints.
+
+- Namespace compliance:
+  - Validates that elements and attributes belong to the correct namespaces as defined in the schema.
+  - Detects namespace mismatches or missing namespace declarations.
+
+- Group model violations:
+  - Validates conformance with `<xsd:choice>` and `<xsd:all>` group models, ensuring correct usage of child elements as per the schema.
+
+- Referential constraints:
+  - Checks for violations in `<xsd:key>`, `<xsd:keyref>`, and `<xsd:unique>` constraints.
+
+- Document structure and completeness:
+  - Ensures that the XML document adheres to the hierarchical structure defined by the schema.
+  - Detects incomplete or improperly nested elements.
+
+- General schema violations:
+  - Detects schema-level issues, such as invalid imports or includes, during schema compilation if they affect validation.
+
+#### Malformed XML
+
+Malformed XML errors arise from issues that prevent the XML file from being parsed at all, before schema validation can even occur. These errors typically reflect syntactic problems in the structure or encoding of the XML content.
+
+Typical cases include:
+
+- Mismatched tags
+  - Opening and closing tags do not match.
+  - Example: `<Title>My Book</title>`
+
+- Unclosed elements
+  - Elements are left unclosed or self-closing syntax is incorrect.
+  - Example: `<Price>12.99`
+
+- Premature end-of-file
+  - The file ends abruptly before all tags are closed, often due to truncation or corruption.
+  - Example: `<Product><ID>123`
+
+- Invalid characters or encoding
+  - The XML includes characters that are not valid in the declared encoding or in XML itself.
+  - Example: Control characters or non-UTF-8 bytes.
+
+- Misused namespaces
+  - Prefixes declared but not bound, or invalid namespace URIs used.
+
+- Declaration errors
+  - Malformed or duplicate `<?xml ... ?>` declarations.
+
+#### File-level issues
+
+General errors that do not pertain to syntax or schema issues:
+
+| Error Type   | Description                               |
+|--------------|-------------------------------------------|
+| Missing File | The specified XML file could not be found |
+| Empty File   | The file exists but is completely empty   |
+| Wrong Format | The file is not `.xml` or `.xsd`          |
+
+#### Final note on error collection
+
+On account of the purpose of this library, all encountered errors (regardless the involved types) are collected and reported. The validator analyzes all files, collects encountered errors (if any) and, finally, reports the results of the run in the console and in the Robot Framework log.
+
+Every test case in which one or more errors have been collected, will receive status FAIL unless `fail_on_errors=True` (see earlier explanations).
 
 ### Keyword documentation
 
-See [keyword documention](docs/XmlValidator.html).
+See the [keyword documentation](https://michaelhallik.github.io/robotframework-xmlvalidator/XmlValidator.html).
 
 The keyword documentation provides detailed descriptions of all functionalities, features and the various ways in which the library and its keywords can be employed.
 
@@ -287,6 +433,10 @@ Validate Folder With Multiple Schemas By File Name
     Validate Xml Files    ${FOLDER_MULTIPLE_XML_XSD_FN}    xsd_search_strategy=by_file_name
 ```
 
+#### Demo test suite file as examples
+
+See the [demo test suite](test/demo/demo.robot) for a demo test suite that demonstrates the most important features of the library in a concise fashion.
+
 #### Integration tests as examples
 
 Note that the [integration test](test/integration) folder contains seven Robot Framework test suite files.
@@ -403,7 +553,7 @@ These are the facets (or attributes) that can be collected and reported for each
 | `severity`    | The severity level of the error (not always present).                      |
 | `args`        | The arguments passed to the error message formatting.        
 
-Use the `error_facets` arg to set which error details to collect.
+Use the `error_facets` argument to set which error details to collect.
 
 For each error that is encountered, the selected error facet(s) will be collected and reported.
 
@@ -413,7 +563,7 @@ You can customize which error facet(s) should be collected, by passing a list of
 
 Error facets passed during library initialization will be overruled by error facets that are passed at the test case level, when calling the `Validate Xml Files` keyword.
 
-The values you can pass through the `error_facets` argument are based on the attributes of the error objects as returned by the XMLSchema.iter_errors() method, that is provided by the xmlschema library and the the xmlvalidator library leverages. Said method yields instances of xmlschema.validators.exceptions.XMLSchemaValidationError (or its subclasses), each representing a specific validation issue encountered in an XML file. These error objects expose various attributes that describe the nature, location, and cause of the problem.
+The values you can pass through the `error_facets` argument are based on the attributes of the error objects as returned by the XMLSchema.iter_errors() method, that is provided by the xmlschema library and the xmlvalidator library leverages. Said method yields instances of xmlschema.validators.exceptions.XMLSchemaValidationError (or its subclasses), each representing a specific validation issue encountered in an XML file. These error objects expose various attributes that describe the nature, location, and cause of the problem.
 
 The table lists the most commonly available attributes, though additional fields may be available depending on the type of validation error.
 
@@ -427,7 +577,7 @@ The table lists the most commonly available attributes, though additional fields
 | [CHANGELOG](CHANGELOG.md) | User / Dev | Version history, features |
 | [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) | Dev | Community guidelines |
 | [CONTRIBUTING](CONTRIBUTING.md) | Dev | Contribute |
-| [Mermaid diagram of GitHub Actions](github_actions.md) | Dev | CI, GitHub Actions |
+| [Mermaid diagram of GitHub Actions](docs/images/github_actions.md) | Dev | CI, GitHub Actions |
 | [License](LICENSE) | All | Legal usage terms |
 | [Make file](Makefile) | Dev | Automation, commands |
 | [Project Structure](project_structure.txt) | Dev | Project layout |
@@ -450,7 +600,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 The overall process:
 
-![Contributing to the project](./docs/images/contributing.JPG)
+![Contributing to robotframework-xmlvalidator](./docs/images/contributing.JPG)
 
 This project uses Poetry for dependency and packaging management.
 
@@ -475,7 +625,7 @@ poetry install
 poetry shell
 ```
 
-Or, if you use a different virt env, activate that.
+Or, if you use a different virt environment, activate that.
 
 ### Running tests
 
@@ -535,7 +685,7 @@ GitHub Actions CI is defined under [github/workflows/](.github/workflows/), in p
 
 The test workflow:
 
-![Test workflow diagram](./docs/images/test_workflow.JPG)
+![Workflow diagram for the robotframework-xmlvalidator project](./docs/images/test_workflow.JPG)
   
 In [.github/](.github/) you’ll also find the various contribution templates:
 
@@ -675,6 +825,18 @@ requirements.txt                     # Requirements file for users (pip)
 
 ---
 
+## Changelog
+
+For a list of changes across versions, including recent behavioral changes in validation logic, see the [CHANGELOG](https://github.com/MichaelHallik/robotframework-xmlvalidator/blob/main/CHANGELOG.md).
+
+---
+
+## Roadmap
+
+See the [project roadmap](ROADMAP.md) for upcoming features and ideas.
+
+---
+
 ## License
 
 Licensed under the Apache License 2.0. See [LICENSE](LICENSE).