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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. {robotframework_xmlvalidator-1.0.0 → robotframework_xmlvalidator-1.0.1}/PKG-INFO +112 -15
  2. {robotframework_xmlvalidator-1.0.0 → robotframework_xmlvalidator-1.0.1}/README.md +111 -14
  3. {robotframework_xmlvalidator-1.0.0 → robotframework_xmlvalidator-1.0.1}/pyproject.toml +1 -1
  4. {robotframework_xmlvalidator-1.0.0 → robotframework_xmlvalidator-1.0.1}/src/xmlvalidator/XmlValidator.py +130 -87
  5. {robotframework_xmlvalidator-1.0.0 → robotframework_xmlvalidator-1.0.1}/src/xmlvalidator/__init__.py +1 -1
  6. {robotframework_xmlvalidator-1.0.0 → robotframework_xmlvalidator-1.0.1}/src/xmlvalidator/xml_validator_results.py +2 -2
  7. {robotframework_xmlvalidator-1.0.0 → robotframework_xmlvalidator-1.0.1}/src/xmlvalidator/xml_validator_utils.py +1 -1
  8. {robotframework_xmlvalidator-1.0.0 → robotframework_xmlvalidator-1.0.1}/LICENSE +0 -0
{robotframework_xmlvalidator-1.0.0 → robotframework_xmlvalidator-1.0.1}/PKG-INFO RENAMED
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.3
2
2
  Name: robotframework-xmlvalidator
3
- Version: 1.0.0
3
+ Version: 1.0.1
4
4
  Summary: A Robot Framework test library for validating XML files against XSD schemas
5
5
  License: Apache-2.0
6
6
  Keywords: robotframework,xml,xsd,validation,test-library,test,testing,test-automation
@@ -25,9 +25,14 @@ Project-URL: Homepage, https://github.com/MichaelHallik/robotframework-xmlvalida
25
25
  Project-URL: Repository, https://github.com/MichaelHallik/robotframework-xmlvalidator
26
26
  Description-Content-Type: text/markdown
27
27
 
28
- [![PyPI version](https://img.shields.io/pypi/v/robotframework-xmlvalidator.svg)](https://pypi.org/project/robotframework-xmlvalidator/)
29
- [![License](https://img.shields.io/pypi/l/robotframework-xmlvalidator)](LICENSE)
30
- [![Tests](https://github.com/MichaelHallik/robotframework-xmlvalidator/actions/workflows/test.yml/badge.svg)](https://github.com/MichaelHallik/robotframework-xmlvalidator/actions/workflows/test.yml)
28
+ | Version | License | Tests |
29
+ |---------|---------|-------|
30
+ | [![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) |
31
+
32
+ | Downloads | Update Badge |
33
+ |-----------|---------------|
34
+ | [![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) |
35
+
31
36
 
32
37
  <details>
33
38
  <summary><strong>📚 Table of Contents</strong></summary>
@@ -51,6 +56,11 @@ Description-Content-Type: text/markdown
51
56
  - [Further examples](#further-examples)
52
57
  - [Using the library](#using-the-library)
53
58
  - [Keyword overview](#keyword-overview)
59
+ - [Error collection](#error-collection)
60
+ - [XSD Schema violations.](#xsd-schema-violations)
61
+ - [Malformed XML](#malformed-xml)
62
+ - [File-level issues](#file-level-issues)
63
+ - [Final note on error collection](#final-note-on-error-collection)
54
64
  - [Keyword documentation](#keyword-documentation)
55
65
  - [Keyword example usage](#keyword-example-usage)
56
66
  - [A few basic examples](#a-few-basic-examples)
@@ -99,7 +109,7 @@ It provides structured and detailed reporting of XML parse errors (malformed XML
99
109
  - Customizable error attributes (`path`, `reason`, `message`, etc.)
100
110
  - Batch validation and per-file error tracking
101
111
  - Export collected errors to CSV (with optional file name timestamping).
102
- - And more (see below and the keyword documentation).
112
+ - And more.
103
113
 
104
114
  ---
105
115
 
@@ -230,19 +240,106 @@ That is, when it encounters an error in a file, it does not fail. Rather, it col
230
240
 
231
241
  In that fashion the keyword works through the entire set of files.
232
242
 
233
- 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.
243
+ 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.
234
244
 
235
- 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.
245
+ 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, 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.
236
246
 
237
247
  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).
238
248
 
239
249
  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.
240
250
 
241
- See for more details the keyword documentation.
251
+ For more details, please see the [keyword documentation](https://michaelhallik.github.io/robotframework-xmlvalidator/XmlValidator.html).
252
+
253
+ ### Error collection
254
+
255
+ Errors that are collected and reported can be categorized as follows:
256
+
257
+ #### XSD Schema violations.
258
+
259
+ - Missing or extra elements that violate cardinality rules, e.g.:
260
+ - Verifies that all mandatory elements (minOccurs > 0) are present in the XML.
261
+ - Ensures that optional elements (minOccurs = 0) do not exceed their maximum allowed occurrences (maxOccurs).
262
+
263
+ - Sequence and order violations:
264
+ - Validates the order of child elements within a parent element if the schema specifies a sequence model (`<xsd:sequence>`).
265
+ - Detects elements that are out of order or missing in a sequence.
266
+
267
+ - Datatype violations:
268
+ - Ensures that element and attribute values conform to their specified datatypes (e.g., xs:string, xs:integer, xs:dateTime).
269
+ - Identifies invalid formats, such as incorrect date or time formats for xs:date and xs:dateTime.
270
+
271
+ - Pattern and enumeration violations:
272
+ - Checks that values conform to patterns defined using `<xsd:pattern>`.
273
+ - Ensures that values fall within allowed enumerations specified in the schema.
274
+
275
+ - Attribute validation:
276
+ - Verifies that required attributes are present.
277
+ - Ensures that attribute values adhere to their declared datatypes and constraints.
278
+
279
+ - Namespace compliance:
280
+ - Validates that elements and attributes belong to the correct namespaces as defined in the schema.
281
+ - Detects namespace mismatches or missing namespace declarations.
282
+
283
+ - Group model violations:
284
+ - Validates conformance with `<xsd:choice>` and `<xsd:all>` group models, ensuring correct usage of child elements as per the schema.
285
+
286
+ - Referential constraints:
287
+ - Checks for violations in `<xsd:key>`, `<xsd:keyref>`, and `<xsd:unique>` constraints.
288
+
289
+ - Document structure and completeness:
290
+ - Ensures that the XML document adheres to the hierarchical structure defined by the schema.
291
+ - Detects incomplete or improperly nested elements.
292
+
293
+ - General schema violations:
294
+ - Detects schema-level issues, such as invalid imports or includes, during schema compilation if they affect validation.
295
+
296
+ #### Malformed XML
297
+
298
+ 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.
299
+
300
+ Typical cases include:
301
+
302
+ - Mismatched tags
303
+ - Opening and closing tags do not match.
304
+ - Example: `<Title>My Book</title>`
305
+
306
+ - Unclosed elements
307
+ - Elements are left unclosed or self-closing syntax is incorrect.
308
+ - Example: `<Price>12.99`
309
+
310
+ - Premature end-of-file
311
+ - The file ends abruptly before all tags are closed, often due to truncation or corruption.
312
+ - Example: `<Product><ID>123`
313
+
314
+ - Invalid characters or encoding
315
+ - The XML includes characters that are not valid in the declared encoding or in XML itself.
316
+ - Example: Control characters or non-UTF-8 bytes.
317
+
318
+ - Misused namespaces
319
+ - Prefixes declared but not bound, or invalid namespace URIs used.
320
+
321
+ - Declaration errors
322
+ - Malformed or duplicate `<?xml ... ?>` declarations.
323
+
324
+ #### File-level issues
325
+
326
+ General errors that do not pertain to syntax or schema issues:
327
+
328
+ | Error Type | Description |
329
+ |--------------|-------------------------------------------|
330
+ | Missing File | The specified XML file could not be found |
331
+ | Empty File | The file exists but is completely empty |
332
+ | Wrong Format | The file is not `.xml` or `.xsd` |
333
+
334
+ #### Final note on error collection
335
+
336
+ 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
337
+
338
+ If you want the test run to receive a FAIL status when, at the end of test run, one or more errors have been found, then set: `fail_on_errors=True`.
242
339
 
243
340
  ### Keyword documentation
244
341
 
245
- See [keyword documention](docs/XmlValidator.html).
342
+ See the [keyword documentation](https://michaelhallik.github.io/robotframework-xmlvalidator/XmlValidator.html).
246
343
 
247
344
  The keyword documentation provides detailed descriptions of all functionalities, features and the various ways in which the library and its keywords can be employed.
248
345
 
@@ -403,7 +500,7 @@ These are the facets (or attributes) that can be collected and reported for each
403
500
  | `severity` | The severity level of the error (not always present). |
404
501
  | `args` | The arguments passed to the error message formatting.
405
502
 
406
- Use the `error_facets` arg to set which error details to collect.
503
+ Use the `error_facets` argument to set which error details to collect.
407
504
 
408
505
  For each error that is encountered, the selected error facet(s) will be collected and reported.
409
506
 
@@ -413,7 +510,7 @@ You can customize which error facet(s) should be collected, by passing a list of
413
510
 
414
511
  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.
415
512
 
416
- 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.
513
+ 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.
417
514
 
418
515
  The table lists the most commonly available attributes, though additional fields may be available depending on the type of validation error.
419
516
 
@@ -427,7 +524,7 @@ The table lists the most commonly available attributes, though additional fields
427
524
  | [CHANGELOG](CHANGELOG.md) | User / Dev | Version history, features |
428
525
  | [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) | Dev | Community guidelines |
429
526
  | [CONTRIBUTING](CONTRIBUTING.md) | Dev | Contribute |
430
- | [Mermaid diagram of GitHub Actions](github_actions.md) | Dev | CI, GitHub Actions |
527
+ | [Mermaid diagram of GitHub Actions](docs/images/github_actions.md) | Dev | CI, GitHub Actions |
431
528
  | [License](LICENSE) | All | Legal usage terms |
432
529
  | [Make file](Makefile) | Dev | Automation, commands |
433
530
  | [Project Structure](project_structure.txt) | Dev | Project layout |
@@ -450,7 +547,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
450
547
 
451
548
  The overall process:
452
549
 
453
- ![Contributing to the project](./docs/images/contributing.JPG)
550
+ ![Contributing to robotframework-xmlvalidator](./docs/images/contributing.JPG)
454
551
 
455
552
  This project uses Poetry for dependency and packaging management.
456
553
 
@@ -475,7 +572,7 @@ poetry install
475
572
  poetry shell
476
573
  ```
477
574
 
478
- Or, if you use a different virt env, activate that.
575
+ Or, if you use a different virt environment, activate that.
479
576
 
480
577
  ### Running tests
481
578
 
@@ -535,7 +632,7 @@ GitHub Actions CI is defined under [github/workflows/](.github/workflows/), in p
535
632
 
536
633
  The test workflow:
537
634
 
538
- ![Test workflow diagram](./docs/images/test_workflow.JPG)
635
+ ![Workflow diagram for the robotframework-xmlvalidator project](./docs/images/test_workflow.JPG)
539
636
 
540
637
  In [.github/](.github/) you’ll also find the various contribution templates:
541
638
 
{robotframework_xmlvalidator-1.0.0 → robotframework_xmlvalidator-1.0.1}/README.md RENAMED
@@ -1,6 +1,11 @@
1
- [![PyPI version](https://img.shields.io/pypi/v/robotframework-xmlvalidator.svg)](https://pypi.org/project/robotframework-xmlvalidator/)
2
- [![License](https://img.shields.io/pypi/l/robotframework-xmlvalidator)](LICENSE)
3
- [![Tests](https://github.com/MichaelHallik/robotframework-xmlvalidator/actions/workflows/test.yml/badge.svg)](https://github.com/MichaelHallik/robotframework-xmlvalidator/actions/workflows/test.yml)
1
+ | Version | License | Tests |
2
+ |---------|---------|-------|
3
+ | [![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) |
4
+
5
+ | Downloads | Update Badge |
6
+ |-----------|---------------|
7
+ | [![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) |
8
+
4
9
 
5
10
  <details>
6
11
  <summary><strong>📚 Table of Contents</strong></summary>
@@ -24,6 +29,11 @@
24
29
  - [Further examples](#further-examples)
25
30
  - [Using the library](#using-the-library)
26
31
  - [Keyword overview](#keyword-overview)
32
+ - [Error collection](#error-collection)
33
+ - [XSD Schema violations.](#xsd-schema-violations)
34
+ - [Malformed XML](#malformed-xml)
35
+ - [File-level issues](#file-level-issues)
36
+ - [Final note on error collection](#final-note-on-error-collection)
27
37
  - [Keyword documentation](#keyword-documentation)
28
38
  - [Keyword example usage](#keyword-example-usage)
29
39
  - [A few basic examples](#a-few-basic-examples)
@@ -72,7 +82,7 @@ It provides structured and detailed reporting of XML parse errors (malformed XML
72
82
  - Customizable error attributes (`path`, `reason`, `message`, etc.)
73
83
  - Batch validation and per-file error tracking
74
84
  - Export collected errors to CSV (with optional file name timestamping).
75
- - And more (see below and the keyword documentation).
85
+ - And more.
76
86
 
77
87
  ---
78
88
 
@@ -203,19 +213,106 @@ That is, when it encounters an error in a file, it does not fail. Rather, it col
203
213
 
204
214
  In that fashion the keyword works through the entire set of files.
205
215
 
206
- 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.
216
+ 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.
207
217
 
208
- 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.
218
+ 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, 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.
209
219
 
210
220
  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).
211
221
 
212
222
  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.
213
223
 
214
- See for more details the keyword documentation.
224
+ For more details, please see the [keyword documentation](https://michaelhallik.github.io/robotframework-xmlvalidator/XmlValidator.html).
225
+
226
+ ### Error collection
227
+
228
+ Errors that are collected and reported can be categorized as follows:
229
+
230
+ #### XSD Schema violations.
231
+
232
+ - Missing or extra elements that violate cardinality rules, e.g.:
233
+ - Verifies that all mandatory elements (minOccurs > 0) are present in the XML.
234
+ - Ensures that optional elements (minOccurs = 0) do not exceed their maximum allowed occurrences (maxOccurs).
235
+
236
+ - Sequence and order violations:
237
+ - Validates the order of child elements within a parent element if the schema specifies a sequence model (`<xsd:sequence>`).
238
+ - Detects elements that are out of order or missing in a sequence.
239
+
240
+ - Datatype violations:
241
+ - Ensures that element and attribute values conform to their specified datatypes (e.g., xs:string, xs:integer, xs:dateTime).
242
+ - Identifies invalid formats, such as incorrect date or time formats for xs:date and xs:dateTime.
243
+
244
+ - Pattern and enumeration violations:
245
+ - Checks that values conform to patterns defined using `<xsd:pattern>`.
246
+ - Ensures that values fall within allowed enumerations specified in the schema.
247
+
248
+ - Attribute validation:
249
+ - Verifies that required attributes are present.
250
+ - Ensures that attribute values adhere to their declared datatypes and constraints.
251
+
252
+ - Namespace compliance:
253
+ - Validates that elements and attributes belong to the correct namespaces as defined in the schema.
254
+ - Detects namespace mismatches or missing namespace declarations.
255
+
256
+ - Group model violations:
257
+ - Validates conformance with `<xsd:choice>` and `<xsd:all>` group models, ensuring correct usage of child elements as per the schema.
258
+
259
+ - Referential constraints:
260
+ - Checks for violations in `<xsd:key>`, `<xsd:keyref>`, and `<xsd:unique>` constraints.
261
+
262
+ - Document structure and completeness:
263
+ - Ensures that the XML document adheres to the hierarchical structure defined by the schema.
264
+ - Detects incomplete or improperly nested elements.
265
+
266
+ - General schema violations:
267
+ - Detects schema-level issues, such as invalid imports or includes, during schema compilation if they affect validation.
268
+
269
+ #### Malformed XML
270
+
271
+ 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.
272
+
273
+ Typical cases include:
274
+
275
+ - Mismatched tags
276
+ - Opening and closing tags do not match.
277
+ - Example: `<Title>My Book</title>`
278
+
279
+ - Unclosed elements
280
+ - Elements are left unclosed or self-closing syntax is incorrect.
281
+ - Example: `<Price>12.99`
282
+
283
+ - Premature end-of-file
284
+ - The file ends abruptly before all tags are closed, often due to truncation or corruption.
285
+ - Example: `<Product><ID>123`
286
+
287
+ - Invalid characters or encoding
288
+ - The XML includes characters that are not valid in the declared encoding or in XML itself.
289
+ - Example: Control characters or non-UTF-8 bytes.
290
+
291
+ - Misused namespaces
292
+ - Prefixes declared but not bound, or invalid namespace URIs used.
293
+
294
+ - Declaration errors
295
+ - Malformed or duplicate `<?xml ... ?>` declarations.
296
+
297
+ #### File-level issues
298
+
299
+ General errors that do not pertain to syntax or schema issues:
300
+
301
+ | Error Type | Description |
302
+ |--------------|-------------------------------------------|
303
+ | Missing File | The specified XML file could not be found |
304
+ | Empty File | The file exists but is completely empty |
305
+ | Wrong Format | The file is not `.xml` or `.xsd` |
306
+
307
+ #### Final note on error collection
308
+
309
+ 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
310
+
311
+ If you want the test run to receive a FAIL status when, at the end of test run, one or more errors have been found, then set: `fail_on_errors=True`.
215
312
 
216
313
  ### Keyword documentation
217
314
 
218
- See [keyword documention](docs/XmlValidator.html).
315
+ See the [keyword documentation](https://michaelhallik.github.io/robotframework-xmlvalidator/XmlValidator.html).
219
316
 
220
317
  The keyword documentation provides detailed descriptions of all functionalities, features and the various ways in which the library and its keywords can be employed.
221
318
 
@@ -376,7 +473,7 @@ These are the facets (or attributes) that can be collected and reported for each
376
473
  | `severity` | The severity level of the error (not always present). |
377
474
  | `args` | The arguments passed to the error message formatting.
378
475
 
379
- Use the `error_facets` arg to set which error details to collect.
476
+ Use the `error_facets` argument to set which error details to collect.
380
477
 
381
478
  For each error that is encountered, the selected error facet(s) will be collected and reported.
382
479
 
@@ -386,7 +483,7 @@ You can customize which error facet(s) should be collected, by passing a list of
386
483
 
387
484
  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.
388
485
 
389
- 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.
486
+ 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.
390
487
 
391
488
  The table lists the most commonly available attributes, though additional fields may be available depending on the type of validation error.
392
489
 
@@ -400,7 +497,7 @@ The table lists the most commonly available attributes, though additional fields
400
497
  | [CHANGELOG](CHANGELOG.md) | User / Dev | Version history, features |
401
498
  | [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) | Dev | Community guidelines |
402
499
  | [CONTRIBUTING](CONTRIBUTING.md) | Dev | Contribute |
403
- | [Mermaid diagram of GitHub Actions](github_actions.md) | Dev | CI, GitHub Actions |
500
+ | [Mermaid diagram of GitHub Actions](docs/images/github_actions.md) | Dev | CI, GitHub Actions |
404
501
  | [License](LICENSE) | All | Legal usage terms |
405
502
  | [Make file](Makefile) | Dev | Automation, commands |
406
503
  | [Project Structure](project_structure.txt) | Dev | Project layout |
@@ -423,7 +520,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
423
520
 
424
521
  The overall process:
425
522
 
426
- ![Contributing to the project](./docs/images/contributing.JPG)
523
+ ![Contributing to robotframework-xmlvalidator](./docs/images/contributing.JPG)
427
524
 
428
525
  This project uses Poetry for dependency and packaging management.
429
526
 
@@ -448,7 +545,7 @@ poetry install
448
545
  poetry shell
449
546
  ```
450
547
 
451
- Or, if you use a different virt env, activate that.
548
+ Or, if you use a different virt environment, activate that.
452
549
 
453
550
  ### Running tests
454
551
 
@@ -508,7 +605,7 @@ GitHub Actions CI is defined under [github/workflows/](.github/workflows/), in p
508
605
 
509
606
  The test workflow:
510
607
 
511
- ![Test workflow diagram](./docs/images/test_workflow.JPG)
608
+ ![Workflow diagram for the robotframework-xmlvalidator project](./docs/images/test_workflow.JPG)
512
609
 
513
610
  In [.github/](.github/) you’ll also find the various contribution templates:
514
611
 
{robotframework_xmlvalidator-1.0.0 → robotframework_xmlvalidator-1.0.1}/pyproject.toml RENAMED
@@ -1,7 +1,7 @@
1
1
  # General.
2
2
  [tool.poetry]
3
3
  name = "robotframework-xmlvalidator"
4
- version = "1.0.0"
4
+ version = "1.0.1"
5
5
  description = "A Robot Framework test library for validating XML files against XSD schemas"
6
6
  authors = ["Michael Hallik <hallik.michael@gmail.com>"]
7
7
  license = "Apache-2.0"
{robotframework_xmlvalidator-1.0.0 → robotframework_xmlvalidator-1.0.1}/src/xmlvalidator/XmlValidator.py RENAMED
@@ -40,9 +40,9 @@ or executed as a Python module via a direct call.
40
40
  """
41
41
 
42
42
 
43
- # pylint: disable=C0103:invalid-name # On account of the module name, that is not snake-cased (required by Robot Framework).
44
- # pylint: disable=C0302:too-many-lines # On account of the extensive docstrings and annotations.
45
- # pylint: disable=C0301:line-too-long # On account of tables in docstrings.
43
+ # pylint: disable=C0103:invalid-name # On account of the module name, that is not snake-cased (required by Robot Framework).
44
+ # pylint: disable=C0302:too-many-lines # On account of the extensive docstrings and annotations.
45
+ # pylint: disable=C0301:line-too-long # On account of tables in docstrings.
46
46
 
47
47
 
48
48
  # Standard library imports.
@@ -82,9 +82,9 @@ class XmlValidator:
82
82
  The other keywords are convenience/helper functions, e.g. ``Reset
83
83
  Error Facets``.
84
84
 
85
- The ``Validate Xml Files`` validates one or more XML files against one
86
- or more XSD schema files and collects and reports all encountered
87
- errors.
85
+ The ``Validate Xml Files`` validates one or more XML files against
86
+ one or more XSD schema files and collects and reports all
87
+ encountered errors.
88
88
 
89
89
  The type of error that the keyword can detect is not limited to XSD
90
90
  violations, but may also pertain to malformed XML files (e.g. parse
@@ -92,9 +92,9 @@ class XmlValidator:
92
92
  others.
93
93
 
94
94
  Errors that result from malformed XML files or from XSD violations
95
- support detailed error reporting. Using the ``error_facets`` argument
96
- you may specify the details the keyword should collect and report
97
- about captured errors.
95
+ support detailed error reporting. Using the ``error_facets``
96
+ argument you may specify the details the keyword should collect and
97
+ report about captured errors.
98
98
 
99
99
  When operating in batch mode, the ``Validate Xml Files`` keyword
100
100
  always validates the entire set of passed XML files. That is, when
@@ -402,16 +402,16 @@ class XmlValidator:
402
402
 
403
403
  """
404
404
 
405
- __version__ = '1.0.0'
405
+ __version__ = '1.0.1'
406
406
  ROBOT_LIBRARY_DOC_FORMAT = 'reST'
407
407
  nr_instances = 0
408
408
 
409
409
  def __init__(
410
- self,
411
- xsd_path: Optional[str | Path] = None,
412
- base_url: Optional[str] = None,
413
- error_facets: Optional[ List[str] ] = None
414
- ) -> None:
410
+ self,
411
+ xsd_path: Optional[str|Path] = None,
412
+ base_url: Optional[str] = None,
413
+ error_facets: Optional[List[str]] = None
414
+ ) -> None:
415
415
  """
416
416
  **Library Scope**
417
417
 
@@ -549,41 +549,10 @@ class XmlValidator:
549
549
  self.validator_utils = ValidatorUtils()
550
550
  self.validator_results = ValidatorResultRecorder()
551
551
  # Initialize the xsd schema from the xsd_path, if provided.
552
- if xsd_path:
553
- # Try to get a single xsd file from the provided xsd_path.
554
- xsd_file_path, is_single_xsd_file = (
555
- self.validator_utils.get_file_paths(
556
- xsd_path, 'xsd'
557
- )
558
- )
559
- # We need (a path to) a single xsd file.
560
- if not is_single_xsd_file:
561
- raise ValueError(f"Got multiple xsd files: {xsd_file_path}.")
562
- # Handle incorrect file extension.
563
- if xsd_file_path[0].suffix != '.xsd':
564
- # Raise a load error.
565
- raise SystemError(
566
- f"ValueError: {xsd_file_path[0]} is not an XSD file."
567
- )
568
- # Try to load the provided XSD file.
569
- result = self._load_schema(xsd_file_path[0], base_url )
570
- if result.success:
571
- # Set the loaded XSD file as default schema.
572
- self.schema = result.value
573
- logger.info(
574
- f"Schema '{self.schema.name}' set.", # type: ignore
575
- also_console=True)
576
- else:
577
- # Or report the load error.
578
- raise SystemError(f"Loading of schema failed: {result.error}")
579
- # Or inform the user on what to do.
580
- else:
581
- logger.info(
582
- "No XSD schema set: provide schema(s) during keyword calls.",
583
- also_console=True
584
- )
585
- # And flag the schema attr as None.
586
- self.schema = None
552
+ self.schema = self._try_load_initial_schema(
553
+ xsd_path=xsd_path,
554
+ base_url=base_url
555
+ )
587
556
  # Set the error facets to collect for failed XML validations.
588
557
  self.error_facets = error_facets if error_facets else [
589
558
  'path', 'reason'
@@ -597,14 +566,14 @@ class XmlValidator:
597
566
  logger.info(f'Number of library instances: {self.nr_instances}.')
598
567
 
599
568
  def _determine_validations(
600
- self,
601
- xml_paths: List[Path],
602
- xsd_path: Optional[str|Path] = None,
603
- xsd_search_strategy: Optional[
569
+ self,
570
+ xml_paths: List[Path],
571
+ xsd_path: Optional[str|Path] = None,
572
+ xsd_search_strategy: Optional[
604
573
  Literal['by_namespace', 'by_file_name']
605
574
  ] = None,
606
- base_url: Optional[str] = None
607
- ) -> Dict[Path, Path | None]:
575
+ base_url: Optional[str] = None
576
+ ) -> Dict[Path, Path | None]:
608
577
  """
609
578
  Constructs a mapping between XML files and the XSD schemas to
610
579
  use for their validation.
@@ -744,10 +713,10 @@ class XmlValidator:
744
713
  return validations
745
714
 
746
715
  def _ensure_schema(
747
- self,
748
- xsd_path: Optional[Path] = None,
749
- base_url: Optional[str] = None
750
- ) -> ValidatorResult:
716
+ self,
717
+ xsd_path: Optional[Path] = None,
718
+ base_url: Optional[str] = None
719
+ ) -> ValidatorResult:
751
720
  """
752
721
  Ensures that a schema is available for validation.
753
722
 
@@ -829,15 +798,12 @@ class XmlValidator:
829
798
  return self._load_schema(xsd_path, base_url) # pyright: ignore
830
799
 
831
800
  def _find_schemas(
832
- self,
833
- xml_file_paths: List[Path],
834
- xsd_file_paths: List[Path],
835
- search_by: Literal[
836
- 'by_namespace',
837
- 'by_file_name'
838
- ] = 'by_namespace',
839
- base_url: Optional[str] = None
840
- ) -> Dict[ Path, Path | None ]:
801
+ self,
802
+ xml_file_paths: List[Path],
803
+ xsd_file_paths: List[Path],
804
+ search_by: Literal['by_namespace', 'by_file_name'] = 'by_namespace',
805
+ base_url: Optional[str] = None
806
+ ) -> Dict[ Path, Path | None ]:
841
807
  """
842
808
  Finds matching XSD schemas for XML files using the specified
843
809
  search strategy.
@@ -982,10 +948,10 @@ class XmlValidator:
982
948
  return validations
983
949
 
984
950
  def _load_schema(
985
- self,
986
- xsd_path: Path,
987
- base_url: Optional[str] = None
988
- ) -> ValidatorResult:
951
+ self,
952
+ xsd_path: Path,
953
+ base_url: Optional[str] = None
954
+ ) -> ValidatorResult:
989
955
  """
990
956
  This method is responsible for initializing a schema object,
991
957
  using the `xmlschema` library.
@@ -1036,17 +1002,96 @@ class XmlValidator:
1036
1002
  success=False, error={"XMLSchemaValidationError": e}
1037
1003
  )
1038
1004
 
1039
- def _validate_xml(self, # pylint: disable=R0913:too-many-arguments disable=R0917:too-many-positional-arguments
1040
- xml_file_path: Path,
1041
- xsd_file_path: Optional[Path] = None,
1042
- base_url: Optional[str] = None,
1043
- error_facets: Optional[ List[str] ] = None,
1044
- pre_parse: Optional[bool] = True
1045
- ) -> Tuple[
1046
- bool, Optional[
1047
- List[ dict[str, Any] ]
1048
- ]
1049
- ]:
1005
+ def _try_load_initial_schema(
1006
+ self,
1007
+ xsd_path: Optional[str|Path] = None,
1008
+ base_url: Optional[str] = None
1009
+ ) -> None:
1010
+ """
1011
+ Attempts to resolve, validate, and load a single XSD schema from
1012
+ the provided path.
1013
+
1014
+ This method is invoked during library initialization (i.e.,
1015
+ within `__init__`) when an optional `xsd_path` is provided. If a
1016
+ path is provided, this method expects the path to resolve to
1017
+ exactly one valid`.xsd` file. If successful, the compiled schema
1018
+ is returned and stored in `self.schema`.
1019
+
1020
+ If the path points to a directory, the method searches for a
1021
+ single `.xsd` file inside it. If multiple matching files are
1022
+ found, or if the file extension is incorrect, an error is
1023
+ raised.
1024
+
1025
+ This method is not intended to be used interactively — it is a
1026
+ one-time helper to support declarative schema configuration
1027
+ during import of the test library.
1028
+
1029
+ Args:
1030
+
1031
+ - xsd_path (str):
1032
+ Path to a `.xsd` file or to a directory containing exactly one
1033
+ `.xsd` file.
1034
+ - base_url (Optional[str]):
1035
+ Optional base URL used when parsing the schema, typically to
1036
+ resolve includes.
1037
+
1038
+ Raises:
1039
+
1040
+ - ValueError:
1041
+ If multiple `.xsd` files are found in the provided directory.
1042
+ - SystemError:
1043
+ If the resolved file does not have a `.xsd` extension or the
1044
+ schema fails to load.
1045
+ """
1046
+ if xsd_path:
1047
+ # Try to get a single xsd file from the provided xsd_path.
1048
+ xsd_file_path, is_single_xsd_file = (
1049
+ self.validator_utils.get_file_paths(
1050
+ xsd_path, 'xsd'
1051
+ )
1052
+ )
1053
+ # We need (a path to) a single xsd file.
1054
+ if not is_single_xsd_file:
1055
+ raise ValueError(
1056
+ f"Got multiple xsd files: {xsd_file_path}."
1057
+ )
1058
+ # Handle incorrect file extension.
1059
+ if xsd_file_path[0].suffix != '.xsd':
1060
+ # Raise a load error.
1061
+ raise SystemError(
1062
+ f"ValueError: {xsd_file_path[0]} is not an XSD file."
1063
+ )
1064
+ # Try to load the provided XSD file.
1065
+ result = self._load_schema(xsd_file_path[0], base_url )
1066
+ if result.success:
1067
+ # Set the loaded XSD file as default schema.
1068
+ logger.info(
1069
+ f"Schema '{self.schema.name}' set.", # type: ignore
1070
+ also_console=True)
1071
+ return result.value
1072
+ # Or report the load error.
1073
+ raise SystemError(
1074
+ f"Loading of schema failed: {result.error}"
1075
+ )
1076
+ # Or inform the user on what to do.
1077
+ logger.info(
1078
+ "No XSD schema set: provide schema(s) during keyword calls.",
1079
+ also_console=True
1080
+ )
1081
+ # And explicitly flag the schema attr as None.
1082
+ return None
1083
+
1084
+ def _validate_xml( # pylint: disable=R0913:too-many-arguments disable=R0917:too-many-positional-arguments
1085
+ self,
1086
+ xml_file_path: Path,
1087
+ xsd_file_path: Optional[Path] = None,
1088
+ base_url: Optional[str] = None,
1089
+ error_facets: Optional[ List[str] ] = None,
1090
+ pre_parse: Optional[bool] = True
1091
+ ) -> Tuple[
1092
+ bool,
1093
+ Optional[List[dict[str, Any]]]
1094
+ ]:
1050
1095
  """
1051
1096
  Validates an XML file against the currently loaded or provided
1052
1097
  XSD schema.
@@ -1259,9 +1304,7 @@ class XmlValidator:
1259
1304
  return self.error_facets
1260
1305
 
1261
1306
  @keyword
1262
- def get_schema(
1263
- self,
1264
- return_schema_name: bool = True
1307
+ def get_schema(self,return_schema_name: bool = True
1265
1308
  ) -> Optional[str|XMLSchema]:
1266
1309
  """
1267
1310
  .. raw:: html
{robotframework_xmlvalidator-1.0.0 → robotframework_xmlvalidator-1.0.1}/src/xmlvalidator/__init__.py RENAMED
@@ -55,6 +55,6 @@ try:
55
55
  __version__ = version("robotframework-xmlvalidator")
56
56
  except PackageNotFoundError:
57
57
  # Fall back when package not installed (default version for development).
58
- __version__ = "0.0.1"
58
+ __version__ = "1.0.1"
59
59
  import warnings
60
60
  warnings.warn("Package metadata not found, using fallback version.")
{robotframework_xmlvalidator-1.0.0 → robotframework_xmlvalidator-1.0.1}/src/xmlvalidator/xml_validator_results.py RENAMED
@@ -75,7 +75,7 @@ class ValidatorResultRecorder:
75
75
  and export validation results.
76
76
  """
77
77
 
78
- __version__ = '1.0.0'
78
+ __version__ = '1.0.1'
79
79
 
80
80
  errors_by_file: List[Dict[str, Any]] = field(default_factory=list)
81
81
  validation_summary: Dict[str, List[str]] = field(
@@ -364,7 +364,7 @@ class ValidatorResult: # pylint: disable=R0903:too-few-public-methods
364
364
  Error information if the operation failed.
365
365
  """
366
366
 
367
- __version__ = '0.0.1'
367
+ __version__ = '1.0.1'
368
368
 
369
369
  def __init__(
370
370
  self,
{robotframework_xmlvalidator-1.0.0 → robotframework_xmlvalidator-1.0.1}/src/xmlvalidator/xml_validator_utils.py RENAMED
@@ -67,7 +67,7 @@ class ValidatorUtils:
67
67
  All methods are static and the class maintains no internal state.
68
68
  """
69
69
 
70
- __version__ = '1.0.0'
70
+ __version__ = '1.0.1'
71
71
 
72
72
  @staticmethod
73
73
  def _resolve_path(path: str | Path) -> Path: