# Test Engines for the Asset Administration Shell
[](https://github.com/admin-shell-io/aas-test-engines/actions/workflows/check.yml)
The Asset Administration Shell (AAS) is a standard for Digital Twins.
More information can be found [here](https://industrialdigitaltwin.org/content-hub/downloads).
The tools in this repository offer measures to validate compliance of AAS implementations against the AAS standard.
## Installation
You can install the AAS Test Engines via pip:
<!-- no-check -->
```sh
python -m pip install --upgrade aas_test_engines
```
If you want to try the latest development version, you might want to install from git directly:
<!-- no-check -->
```sh
python -m pip install --upgrade pip install git+https://github.com/admin-shell-io/aas-test-engines.git
```
## Command Line Interface
You may want to invoke the test tools using the command line interface:
<!-- no-check -->
```sh
# Check file
aas_test_engines check_file test.aasx
aas_test_engines check_file test.json --format json
aas_test_engines check_file submodel.aasx --model_type Submodel
# Check server
aas_test_engines check_server https://localhost https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRepositoryServiceSpecification/SSP-002
# Generate test data
aas_test_engines generate_files output_dir
# Alternative output formats (work for all commands)
aas_test_engines check_file test.aasx --output html > output.html
aas_test_engines check_file test.aasx --output json > output.json
```
Note that the Test Engines return zero in case of compliance and non-zero otherwise so that you can integrate them into ci.
For more detailed instructions on how to test your AAS Software, see [Test Setups](#test-setups).
If you want to include the Test Engines into your software, see [Python Module Interface](#python-interface).
## Supported Versions, Suites and Templates
By default, the Test Engines test against the latest version 3.0, precisely: metamodel => 3.0.1 and API => 3.0.3.
In case of Files, the IDTA specifies submodel templates.
For a full list, please visit [AAS Submodel Templates](https://industrialdigitaltwin.org/content-hub/teilmodelle).
The following templates are supported:
| Name | Semantic ID | Support in test-engine |
| :--- | :--- | :--- |
| Contact Information | https://admin-shell.io/zvei/nameplate/1/0/ContactInformations | ✅ |
| Digital Nameplate for Industrial Equipment | https://admin-shell.io/zvei/nameplate/2/0/Nameplate | ✅ |
For a detailed list of what is checked (and what is not), see [here](doc/file.md).
In case of API, the IDTA specifications define service specifications and profiles. Below tables describes the supported API profiles by the current test-engine. For more information about these profiles, please visit [IDTA Specifications for API](https://industrialdigitaltwin.org/wp-content/uploads/2024/10/IDTA-01002-3-0-3_SpecificationAssetAdministrationShell_Part2_API.pdf).
| Name | Profile Identifier | Description | Support in test-engine |
| :--- | :--- | :--- | :--- |
| AAS Repository Read Profile | https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRepositoryServiceSpecification/SSP-002 | Only read operations for the AAS Repository Service | ✅ |
| AAS Read Profile | https://admin-shell.io/aas/API/3/0/AssetAdministrationShellServiceSpecification/SSP-002 | Only read operations for the AAS Service | ✅ |
| Submodel Repository Read Profile | https://admin-shell.io/aas/API/3/0/SubmodelRepositoryServiceSpecification/SSP-002 | Only read operations for the Submodel Repository Service | ✅ |
| Submodel Read Profile | https://admin-shell.io/aas/API/3/0/SubmodelServiceSpecification/SSP-002 | Only read operations for the Submodel Repository Service | ✅ |
| AAS Registry Read Profile | https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRegistryServiceSpecification/SSP-002 | Only read operations for AAS Registry Service | ✅* |
| Submodel Registry Read Profile | https://admin-shell.io/aas/API/3/0/SubmodelRegistryServiceSpecification/SSP-002 | Only read operations for Submodel Registry Service | ✅* |
| Discovery Service Full Profile | https://admin-shell.io/aas/API/3/0/DiscoveryServiceSpecification/SSP-001 | All operations for Discovery Service | ✅* |
| Concept Description Repository Profile | https://admin-shell.io/aas/API/3/0/ConceptDescriptionRepositoryServiceSpecification/SSP-001 | Only Read operations for the Concept Description Service | ✅* |
*IDTA members only
For a detailed list of what is checked (and what is not), see [here](doc/api.md).
## Test Setups
<a name="test-setups"></a>
### Check File for Compliance
Given a file in either AASX package format or XML/JSON "raw" format, you can use the Test Engines to check compliance of these files.
Assuming your file is named `my_aas.aasx`, you can invoke the Test Engines using the command line:
<!-- no-check -->
```sh
aas_test_engines check_file my_aas.aasx
```
This will first check, if your aasx package is correct (in terms of relationships etc.).
Then it checks if all contained AAS are compliant to the meta-model and all constraints hold as defined by Part 1 and Part 3a of the specification.
Finally, the Test Engines will iterate over all submodels in your AAS and check if these are compliant to the corresponding submodel templates.
In case you want to check other formats, use the `--format` parameter:
<!-- no-check -->
```sh
aas_test_engines check_file my_aas.json --format json
aas_test_engines check_file my_aas.xml --format xml
```
### Check Server for compliance
To test compliance of an AAS server to the HTTP/REST API, the Test Engines send a series of requests.
Your server should then answer according to the behavior as defined by Part 2 of the specification.
The Test Engines check the conformance of the responses.
For each operation (aka endpoint) we execute a set of negative tests.
These set parameters to invalid values like negative integers for the `limit` parameter.
Afterwards we execute a set of positive tests which set all parameters to valid values and check the response accordingly.
Before starting the actual testing procedure, you need to populate some test data at your server which is stored at `bin/check_servers/test_data`.
Then you start the testing by running passing the url of your server and a profile name:
<!-- no-check -->
```sh
aas_test_engines check_server \
http://my-server.com/api/v3.0 \
https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRepositoryServiceSpecification/SSP-002
```
This starts the testing procedure which may take some seconds.
You may prefer the HTML output for better readability by running:
<!-- no-check -->
```sh
aas_test_engines check_server \
http://my-server.com/api/v3.0 \
https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRepositoryServiceSpecification/SSP-002 \
--output html > result.html
```
#### Running a Subset of the Tests
By default, all tests of the selected suite/profile are executed.
If you want to limit the test cases to a subset, you can pass `--filter`, so that only operations whose name matches the filter are tested:
<!-- no-check -->
```sh
aas_test_engines check_server ... --filter GetAll*
```
A filter consists of a list of glob patterns separated by `:`.
Every operation whose name matches this glob pattern is executed.
Optionally you can provide negative patterns which start after `~`.
Every operation whose name matches a negative glob pattern is omitted from test execution.
Examples:
* `GetAll*`: Tests all operations starting with `GetAll`
* `GetAll*~GetAllShells`: Tests all operations starting with `GetAll` except for `GetAllShells`
* `*~Post*:Delete*`: Test all operations except for the ones starting with `Post` or `Delete`
#### Handling Authentication
In case your server applies some authentication mechanism for security, you need to pass credentials to the Test Engines.
You can use the `--header` option to do so by providing credentials within header fields:
<!-- no-check -->
```sh
aas_test_engines check_server ... --header 'Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l'
```
If you need a more sophisticated authentication mechanism, you should use the Python module interface and provide your own `aas_test_engines.http.HttpClient` class.
## Python Module Interface
<a name="python-interface"></a>
### Check AAS Type 1 (File)
Check AASX:
```python
from aas_test_engines import file
with open('aas.aasx', 'rb') as f:
result = file.check_aasx_file(f)
# result.ok() == True
result.dump()
# try result.to_html() to get an interactive representation
```
Check JSON:
```python
from aas_test_engines import file
# Check file
with open('aas.json') as f:
result = file.check_json_file(f)
# result.ok() == True
# Or check data directly
aas = {
'assetAdministrationShells': [],
'submodels': [],
'conceptDescriptions': []
}
result = file.check_json_data(aas)
# result.ok() == True
result.dump()
```
Check XML:
```python
from aas_test_engines import file
from xml.etree import ElementTree
# Check file
with open('aas.xml') as f:
result = file.check_xml_file(f)
# result.ok() == True
# Or check data directly
data = ElementTree.fromstring(
'<environment xmlns="https://admin-shell.io/aas/3/0" />')
result = file.check_xml_data(data)
# result.ok() == True
result.dump()
```
Checking older versions:
```python
from aas_test_engines import file
print(file.supported_versions())
print(file.latest_version())
with open('aas.aasx', 'rb') as f:
result = file.check_aasx_file(f, version="3.0")
# result.ok() == True
result.dump()
```
### Check AAS Type 2 (HTTP API)
Check a running server instance:
```python
from aas_test_engines import api, config, http
client = http.HttpClient(
host="http://localhost",
)
conf = config.CheckApiConfig(
suite="https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRepositoryServiceSpecification/SSP-002",
)
result, mat = api.execute_tests(client, conf)
result.dump()
```
To check older versions pass `version` to the `ApiConfig`:
```python
from aas_test_engines import api, config
print(api.supported_versions())
print(api.latest_version())
conf = config.CheckApiConfig(
suite="https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRepositoryServiceSpecification/SSP-002",
version='3.0'
)
```
### Generating test data for software testing
If you develop an AAS application like an AAS editor you may want to use test data to verify correctness of your application.
The test engines allow to generate a set of AAS files which are compliant with the standard and you can therefore use to assess your application as follows:
<!-- no-check -->
```python
from aas_test_engines import file
for is_valid, sample in file.generate():
print(sample) # or whatever you want to do with it
```
Raw data
{
"_id": null,
"home_page": null,
"name": "aas-test-engines",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "asset administration shell, aas, test",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/c8/8b/91465d446e8479dbbb5649d068fee1836a5f4b4756560513d80abf46df9e/aas_test_engines-1.0.3.tar.gz",
"platform": null,
"description": "# Test Engines for the Asset Administration Shell\n\n[](https://github.com/admin-shell-io/aas-test-engines/actions/workflows/check.yml)\n\nThe Asset Administration Shell (AAS) is a standard for Digital Twins.\nMore information can be found [here](https://industrialdigitaltwin.org/content-hub/downloads).\n\nThe tools in this repository offer measures to validate compliance of AAS implementations against the AAS standard.\n\n## Installation\n\nYou can install the AAS Test Engines via pip:\n\n<!-- no-check -->\n```sh\npython -m pip install --upgrade aas_test_engines\n```\n\nIf you want to try the latest development version, you might want to install from git directly:\n\n<!-- no-check -->\n```sh\npython -m pip install --upgrade pip install git+https://github.com/admin-shell-io/aas-test-engines.git\n```\n\n\n\n## Command Line Interface\n\nYou may want to invoke the test tools using the command line interface:\n\n<!-- no-check -->\n```sh\n# Check file\naas_test_engines check_file test.aasx\naas_test_engines check_file test.json --format json\naas_test_engines check_file submodel.aasx --model_type Submodel\n\n# Check server\naas_test_engines check_server https://localhost https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRepositoryServiceSpecification/SSP-002\n\n# Generate test data\naas_test_engines generate_files output_dir\n\n# Alternative output formats (work for all commands)\naas_test_engines check_file test.aasx --output html > output.html\naas_test_engines check_file test.aasx --output json > output.json\n```\n\nNote that the Test Engines return zero in case of compliance and non-zero otherwise so that you can integrate them into ci.\n\nFor more detailed instructions on how to test your AAS Software, see [Test Setups](#test-setups).\nIf you want to include the Test Engines into your software, see [Python Module Interface](#python-interface).\n\n## Supported Versions, Suites and Templates\n\nBy default, the Test Engines test against the latest version 3.0, precisely: metamodel => 3.0.1 and API => 3.0.3.\nIn case of Files, the IDTA specifies submodel templates.\nFor a full list, please visit [AAS Submodel Templates](https://industrialdigitaltwin.org/content-hub/teilmodelle).\nThe following templates are supported:\n| Name | Semantic ID | Support in test-engine |\n| :--- | :--- | :--- |\n| Contact Information | https://admin-shell.io/zvei/nameplate/1/0/ContactInformations | \u2705 |\n| Digital Nameplate for Industrial Equipment | https://admin-shell.io/zvei/nameplate/2/0/Nameplate | \u2705 |\n\nFor a detailed list of what is checked (and what is not), see [here](doc/file.md).\n\nIn case of API, the IDTA specifications define service specifications and profiles. Below tables describes the supported API profiles by the current test-engine. For more information about these profiles, please visit [IDTA Specifications for API](https://industrialdigitaltwin.org/wp-content/uploads/2024/10/IDTA-01002-3-0-3_SpecificationAssetAdministrationShell_Part2_API.pdf).\n\n| Name | Profile Identifier | Description | Support in test-engine |\n| :--- | :--- | :--- | :--- |\n| AAS Repository Read Profile | https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRepositoryServiceSpecification/SSP-002 | Only read operations for the AAS Repository Service | \u2705 |\n| AAS Read Profile | https://admin-shell.io/aas/API/3/0/AssetAdministrationShellServiceSpecification/SSP-002 | Only read operations for the AAS Service | \u2705 |\n| Submodel Repository Read Profile | https://admin-shell.io/aas/API/3/0/SubmodelRepositoryServiceSpecification/SSP-002 | Only read operations for the Submodel Repository Service | \u2705 |\n| Submodel Read Profile | https://admin-shell.io/aas/API/3/0/SubmodelServiceSpecification/SSP-002 | Only read operations for the Submodel Repository Service | \u2705 |\n| AAS Registry Read Profile | https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRegistryServiceSpecification/SSP-002 | Only read operations for AAS Registry Service | \u2705* |\n| Submodel Registry Read Profile | https://admin-shell.io/aas/API/3/0/SubmodelRegistryServiceSpecification/SSP-002 | Only read operations for Submodel Registry Service | \u2705* |\n| Discovery Service Full Profile | https://admin-shell.io/aas/API/3/0/DiscoveryServiceSpecification/SSP-001 | All operations for Discovery Service | \u2705* |\n| Concept Description Repository Profile | https://admin-shell.io/aas/API/3/0/ConceptDescriptionRepositoryServiceSpecification/SSP-001 | Only Read operations for the Concept Description Service | \u2705* |\n\n*IDTA members only\n\nFor a detailed list of what is checked (and what is not), see [here](doc/api.md).\n\n## Test Setups\n<a name=\"test-setups\"></a>\n\n### Check File for Compliance\nGiven a file in either AASX package format or XML/JSON \"raw\" format, you can use the Test Engines to check compliance of these files.\nAssuming your file is named `my_aas.aasx`, you can invoke the Test Engines using the command line:\n<!-- no-check -->\n```sh\naas_test_engines check_file my_aas.aasx\n```\nThis will first check, if your aasx package is correct (in terms of relationships etc.).\nThen it checks if all contained AAS are compliant to the meta-model and all constraints hold as defined by Part 1 and Part 3a of the specification.\nFinally, the Test Engines will iterate over all submodels in your AAS and check if these are compliant to the corresponding submodel templates.\n\nIn case you want to check other formats, use the `--format` parameter:\n<!-- no-check -->\n```sh\naas_test_engines check_file my_aas.json --format json\naas_test_engines check_file my_aas.xml --format xml\n```\n\n### Check Server for compliance\nTo test compliance of an AAS server to the HTTP/REST API, the Test Engines send a series of requests.\nYour server should then answer according to the behavior as defined by Part 2 of the specification.\nThe Test Engines check the conformance of the responses.\nFor each operation (aka endpoint) we execute a set of negative tests.\nThese set parameters to invalid values like negative integers for the `limit` parameter.\nAfterwards we execute a set of positive tests which set all parameters to valid values and check the response accordingly.\n\nBefore starting the actual testing procedure, you need to populate some test data at your server which is stored at `bin/check_servers/test_data`.\nThen you start the testing by running passing the url of your server and a profile name:\n<!-- no-check -->\n```sh\naas_test_engines check_server \\\n http://my-server.com/api/v3.0 \\\n https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRepositoryServiceSpecification/SSP-002\n```\n\nThis starts the testing procedure which may take some seconds.\nYou may prefer the HTML output for better readability by running:\n\n<!-- no-check -->\n```sh\naas_test_engines check_server \\\n http://my-server.com/api/v3.0 \\\n https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRepositoryServiceSpecification/SSP-002 \\\n --output html > result.html\n```\n\n#### Running a Subset of the Tests\nBy default, all tests of the selected suite/profile are executed.\nIf you want to limit the test cases to a subset, you can pass `--filter`, so that only operations whose name matches the filter are tested:\n\n<!-- no-check -->\n```sh\naas_test_engines check_server ... --filter GetAll*\n```\n\nA filter consists of a list of glob patterns separated by `:`.\nEvery operation whose name matches this glob pattern is executed.\nOptionally you can provide negative patterns which start after `~`.\nEvery operation whose name matches a negative glob pattern is omitted from test execution.\n\nExamples:\n* `GetAll*`: Tests all operations starting with `GetAll`\n* `GetAll*~GetAllShells`: Tests all operations starting with `GetAll` except for `GetAllShells`\n* `*~Post*:Delete*`: Test all operations except for the ones starting with `Post` or `Delete`\n\n#### Handling Authentication\nIn case your server applies some authentication mechanism for security, you need to pass credentials to the Test Engines.\nYou can use the `--header` option to do so by providing credentials within header fields:\n\n<!-- no-check -->\n```sh\naas_test_engines check_server ... --header 'Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l'\n```\n\nIf you need a more sophisticated authentication mechanism, you should use the Python module interface and provide your own `aas_test_engines.http.HttpClient` class.\n\n## Python Module Interface\n<a name=\"python-interface\"></a>\n\n### Check AAS Type 1 (File)\n\nCheck AASX:\n\n```python\nfrom aas_test_engines import file\n\nwith open('aas.aasx', 'rb') as f:\n result = file.check_aasx_file(f)\n# result.ok() == True\n\nresult.dump()\n# try result.to_html() to get an interactive representation\n```\n\nCheck JSON:\n\n```python\nfrom aas_test_engines import file\n\n# Check file\nwith open('aas.json') as f:\n result = file.check_json_file(f)\n# result.ok() == True\n\n# Or check data directly\naas = {\n 'assetAdministrationShells': [],\n 'submodels': [],\n 'conceptDescriptions': []\n}\nresult = file.check_json_data(aas)\n# result.ok() == True\n\nresult.dump()\n```\n\nCheck XML:\n\n```python\nfrom aas_test_engines import file\nfrom xml.etree import ElementTree\n\n# Check file\nwith open('aas.xml') as f:\n result = file.check_xml_file(f)\n# result.ok() == True\n\n# Or check data directly\ndata = ElementTree.fromstring(\n '<environment xmlns=\"https://admin-shell.io/aas/3/0\" />')\nresult = file.check_xml_data(data)\n# result.ok() == True\n\nresult.dump()\n```\n\nChecking older versions:\n\n```python\nfrom aas_test_engines import file\n\nprint(file.supported_versions())\nprint(file.latest_version())\nwith open('aas.aasx', 'rb') as f:\n result = file.check_aasx_file(f, version=\"3.0\")\n# result.ok() == True\n\nresult.dump()\n```\n\n### Check AAS Type 2 (HTTP API)\n\nCheck a running server instance:\n\n```python\nfrom aas_test_engines import api, config, http\n\nclient = http.HttpClient(\n host=\"http://localhost\",\n)\nconf = config.CheckApiConfig(\n suite=\"https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRepositoryServiceSpecification/SSP-002\",\n)\n\nresult, mat = api.execute_tests(client, conf)\nresult.dump()\n```\n\nTo check older versions pass `version` to the `ApiConfig`:\n\n```python\nfrom aas_test_engines import api, config\nprint(api.supported_versions())\nprint(api.latest_version())\n\nconf = config.CheckApiConfig(\n suite=\"https://admin-shell.io/aas/API/3/0/AssetAdministrationShellRepositoryServiceSpecification/SSP-002\",\n version='3.0'\n)\n```\n\n### Generating test data for software testing\n\nIf you develop an AAS application like an AAS editor you may want to use test data to verify correctness of your application.\nThe test engines allow to generate a set of AAS files which are compliant with the standard and you can therefore use to assess your application as follows:\n\n<!-- no-check -->\n```python\nfrom aas_test_engines import file\n\nfor is_valid, sample in file.generate():\n print(sample) # or whatever you want to do with it\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Official test tooling for the Asset Administration Shell",
"version": "1.0.3",
"project_urls": {
"Homepage": "https://github.com/admin-shell-io/aas-test-engines"
},
"split_keywords": [
"asset administration shell",
" aas",
" test"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cc03a85b786431668c83ece17ce0d75f41267f9657beb54fc91dbc3096b6a47d",
"md5": "35e8ab1ff196a86ae7a07dee7e4058e5",
"sha256": "06a9fc998313af6b9f2cb912e0268d67861a173ff87b9f8fe8e13c369df0257f"
},
"downloads": -1,
"filename": "aas_test_engines-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "35e8ab1ff196a86ae7a07dee7e4058e5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 59837,
"upload_time": "2025-08-05T08:51:53",
"upload_time_iso_8601": "2025-08-05T08:51:53.691919Z",
"url": "https://files.pythonhosted.org/packages/cc/03/a85b786431668c83ece17ce0d75f41267f9657beb54fc91dbc3096b6a47d/aas_test_engines-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c88b91465d446e8479dbbb5649d068fee1836a5f4b4756560513d80abf46df9e",
"md5": "2ab0f85b5bf549fcec28ede8a4426a64",
"sha256": "6f05ef6c87ad2ff6a80c18c94d71047d39074f89824c940681bfd2759a231634"
},
"downloads": -1,
"filename": "aas_test_engines-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "2ab0f85b5bf549fcec28ede8a4426a64",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 56849,
"upload_time": "2025-08-05T08:51:54",
"upload_time_iso_8601": "2025-08-05T08:51:54.745178Z",
"url": "https://files.pythonhosted.org/packages/c8/8b/91465d446e8479dbbb5649d068fee1836a5f4b4756560513d80abf46df9e/aas_test_engines-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-05 08:51:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "admin-shell-io",
"github_project": "aas-test-engines",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.31"
]
]
},
{
"name": "pyyaml",
"specs": [
[
">=",
"6.0"
]
]
},
{
"name": "json_schema_tool",
"specs": [
[
">=",
"0.4"
]
]
},
{
"name": "jsonpath_ng",
"specs": [
[
">=",
"1.5"
]
]
},
{
"name": "fences",
"specs": [
[
"==",
"1.4.0"
]
]
}
],
"lcname": "aas-test-engines"
}
JSON
