diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 453a6ae08..1ebe4a48c 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -48,6 +48,23 @@ repos: language: script entry: .dev-tools/linting/check-links-to-precice.sh types_or: ["markdown", "html"] +- repo: https://github.com/python-jsonschema/check-jsonschema + rev: 0.39.0 + hooks: + - id: check-metaschema + files: ^tests/schemas/.*\.schema\.json$ + - id: check-jsonschema + name: validate tests.yaml + files: ^tests/tests\.yaml$ + args: [ --schemafile, tests/schemas/tests.schema.json ] + - id: check-jsonschema + name: validate components.yaml + files: ^tests/components\.yaml$ + args: [ --schemafile, tests/schemas/components.schema.json ] + - id: check-jsonschema + name: validate metadata.yaml + files: ^[^/]+/metadata\.yaml$ + args: [ --schemafile, tests/schemas/metadata.schema.json ] - repo: https://github.com/rhysd/actionlint rev: v1.7.12 hooks: diff --git a/aste-turbine/metadata.yaml b/aste-turbine/metadata.yaml index 5c25fefb5..4200a469b 100644 --- a/aste-turbine/metadata.yaml +++ b/aste-turbine/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: ASTE turbine path: aste-turbine url: https://precice.org/tutorials-aste-turbine.html diff --git a/breaking-dam-2d/metadata.yaml b/breaking-dam-2d/metadata.yaml index 786fc691f..77319294e 100644 --- a/breaking-dam-2d/metadata.yaml +++ b/breaking-dam-2d/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Breaking dam 2D path: breaking-dam-2d # relative to git repo url: https://precice.org/tutorials-breaking-dam-2d.html diff --git a/changelog-entries/948.md b/changelog-entries/948.md new file mode 100644 index 000000000..a37fb4ef1 --- /dev/null +++ b/changelog-entries/948.md @@ -0,0 +1 @@ +- Added JSON schemas for `tests.yaml`, `components.yaml`, and the `metadata.yaml` files, which provide editor support and are checked by the pre-commit hooks. [#948](https://github.com/precice/tutorials/pull/948) \ No newline at end of file diff --git a/channel-transport-particles/metadata.yaml b/channel-transport-particles/metadata.yaml index 1fbf0a728..2212bc2da 100644 --- a/channel-transport-particles/metadata.yaml +++ b/channel-transport-particles/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Channel transport particles path: channel-transport-particles url: https://precice.org/tutorials-channel-transport-particles.html diff --git a/channel-transport-reaction/metadata.yaml b/channel-transport-reaction/metadata.yaml index 89e96fe1b..cdcfbb49a 100644 --- a/channel-transport-reaction/metadata.yaml +++ b/channel-transport-reaction/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Channel transport reaction path: channel-transport-reaction url: https://precice.org/tutorials-channel-transport-reaction.html diff --git a/channel-transport/metadata.yaml b/channel-transport/metadata.yaml index 8f4a22470..dc89a913d 100644 --- a/channel-transport/metadata.yaml +++ b/channel-transport/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Channel transport path: channel-transport url: https://precice.org/tutorials-channel-transport.html diff --git a/elastic-tube-1d/metadata.yaml b/elastic-tube-1d/metadata.yaml index 11d90961d..86bf8b902 100644 --- a/elastic-tube-1d/metadata.yaml +++ b/elastic-tube-1d/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Elastic tube 1D path: elastic-tube-1d url: https://precice.org/tutorials-elastic-tube-1d.html diff --git a/elastic-tube-3d/metadata.yaml b/elastic-tube-3d/metadata.yaml index 438888d8b..212bb8758 100644 --- a/elastic-tube-3d/metadata.yaml +++ b/elastic-tube-3d/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Elastic tube 3D path: elastic-tube-3d # relative to git repo url: https://precice.org/tutorials-elastic-tube-3d.html diff --git a/flow-around-controlled-moving-cylinder/metadata.yaml b/flow-around-controlled-moving-cylinder/metadata.yaml index 1c34cc08f..3c6c285d0 100644 --- a/flow-around-controlled-moving-cylinder/metadata.yaml +++ b/flow-around-controlled-moving-cylinder/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Flow around a controlled moving cylinder path: flow-around-controlled-moving-cylinder url: https://precice.org/tutorials-flow-around-controlled-moving-cylinder.html diff --git a/flow-over-heated-plate-nearest-projection/metadata.yaml b/flow-over-heated-plate-nearest-projection/metadata.yaml index 046528f09..5f2a9df24 100644 --- a/flow-over-heated-plate-nearest-projection/metadata.yaml +++ b/flow-over-heated-plate-nearest-projection/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Flow over heated plate nearest projection path: flow-over-heated-plate-nearest-projection url: https://precice.org/tutorials-flow-over-heated-plate-nearest-projection.html diff --git a/flow-over-heated-plate-partitioned-flow/metadata.yaml b/flow-over-heated-plate-partitioned-flow/metadata.yaml index ddd86c96a..018c8829d 100644 --- a/flow-over-heated-plate-partitioned-flow/metadata.yaml +++ b/flow-over-heated-plate-partitioned-flow/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Flow over heated plate partitioned flow path: flow-over-heated-plate-partitioned-flow # relative to git repo url: https://precice.org/tutorials-flow-over-heated-plate-partitioned-flow.html diff --git a/flow-over-heated-plate-steady-state/metadata.yaml b/flow-over-heated-plate-steady-state/metadata.yaml index 1bc65d444..fbf9210fa 100644 --- a/flow-over-heated-plate-steady-state/metadata.yaml +++ b/flow-over-heated-plate-steady-state/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Flow over heated plate steady state path: flow-over-heated-plate-steady-state # relative to git repo url: https://precice.org/tutorials-flow-over-heated-plate-steady-state.html diff --git a/flow-over-heated-plate-two-meshes/metadata.yaml b/flow-over-heated-plate-two-meshes/metadata.yaml index c457cca11..9e803a8b5 100644 --- a/flow-over-heated-plate-two-meshes/metadata.yaml +++ b/flow-over-heated-plate-two-meshes/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Flow over heated plate with two meshes path: flow-over-heated-plate-two-meshes # relative to git repo url: https://precice.org/tutorials-flow-over-heated-plate-two-meshes.html diff --git a/flow-over-heated-plate/metadata.yaml b/flow-over-heated-plate/metadata.yaml index 0b384ba25..b5825ec6d 100644 --- a/flow-over-heated-plate/metadata.yaml +++ b/flow-over-heated-plate/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Flow over heated plate path: flow-over-heated-plate # relative to git repo url: https://precice.org/tutorials-flow-over-heated-plate.html diff --git a/free-flow-over-porous-media/metadata.yaml b/free-flow-over-porous-media/metadata.yaml index d4593f648..b11c4b611 100644 --- a/free-flow-over-porous-media/metadata.yaml +++ b/free-flow-over-porous-media/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Free flow over porous media path: free-flow-over-porous-media url: https://precice.org/tutorials-free-flow-over-porous-media-2d.html diff --git a/heat-exchanger-simplified/metadata.yaml b/heat-exchanger-simplified/metadata.yaml index bf63971a3..95a82064b 100644 --- a/heat-exchanger-simplified/metadata.yaml +++ b/heat-exchanger-simplified/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Heat Exchanger simplified path: heat-exchanger-simplified # relative to git repo url: https://precice.org/tutorials-heat-exchanger-simplified.html diff --git a/heat-exchanger/metadata.yaml b/heat-exchanger/metadata.yaml index 54974dd77..27f862ccf 100644 --- a/heat-exchanger/metadata.yaml +++ b/heat-exchanger/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Heat exchanger path: heat-exchanger # relative to git repo url: https://precice.org/tutorials-heat-exchanger.html diff --git a/multiple-perpendicular-flaps/metadata.yaml b/multiple-perpendicular-flaps/metadata.yaml index 3c4121b29..bbf93e3d6 100644 --- a/multiple-perpendicular-flaps/metadata.yaml +++ b/multiple-perpendicular-flaps/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Multiple perpendicular flaps path: multiple-perpendicular-flaps url: https://precice.org/tutorials-multiple-perpendicular-flaps.html diff --git a/oscillator-overlap/metadata.yaml b/oscillator-overlap/metadata.yaml index 9c77c5d7b..b0e47b087 100644 --- a/oscillator-overlap/metadata.yaml +++ b/oscillator-overlap/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Oscillator overlap path: oscillator-overlap url: https://precice.org/tutorials-oscillator-overlap.html diff --git a/oscillator/metadata.yaml b/oscillator/metadata.yaml index 10f8c3cb7..65ff9fdd0 100644 --- a/oscillator/metadata.yaml +++ b/oscillator/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Oscillator path: oscillator url: https://precice.org/tutorials-oscillator.html diff --git a/partitioned-backwards-facing-step/metadata.yaml b/partitioned-backwards-facing-step/metadata.yaml index 982e273fd..357fcff56 100644 --- a/partitioned-backwards-facing-step/metadata.yaml +++ b/partitioned-backwards-facing-step/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Partitioned backwards facing step path: partitioned-backwards-facing-step # relative to git repo url: https://precice.org/tutorials-partitioned-backwards-facing-step.html diff --git a/partitioned-burgers-1d/metadata.yaml b/partitioned-burgers-1d/metadata.yaml index 06e7998a4..3c91ecd12 100644 --- a/partitioned-burgers-1d/metadata.yaml +++ b/partitioned-burgers-1d/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Partitioned Burgers' equation 1D path: partitioned-burgers-1d # relative to git repo url: https://precice.org/tutorials-partitioned-burgers-1d.html diff --git a/partitioned-elastic-beam/metadata.yaml b/partitioned-elastic-beam/metadata.yaml index 3d9788f88..2bc435a67 100644 --- a/partitioned-elastic-beam/metadata.yaml +++ b/partitioned-elastic-beam/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Partitioned elastic beam path: partitioned-elastic-beam # relative to git repo url: https://precice.org/tutorials-partitioned-elastic-beam.html diff --git a/partitioned-heat-conduction-3d/metadata.yaml b/partitioned-heat-conduction-3d/metadata.yaml index df957913f..e1fa7c129 100644 --- a/partitioned-heat-conduction-3d/metadata.yaml +++ b/partitioned-heat-conduction-3d/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Partitioned heat conduction 3D path: partitioned-heat-conduction-3d # relative to git repo url: https://precice.org/tutorials-partitioned-heat-conduction-3d.html diff --git a/partitioned-heat-conduction-complex/metadata.yaml b/partitioned-heat-conduction-complex/metadata.yaml index 673a612b3..f3492cf98 100644 --- a/partitioned-heat-conduction-complex/metadata.yaml +++ b/partitioned-heat-conduction-complex/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Partitioned heat conduction complex path: partitioned-heat-conduction-complex # relative to git repo url: https://precice.org/tutorials-partitioned-heat-conduction-complex.html diff --git a/partitioned-heat-conduction-direct/metadata.yaml b/partitioned-heat-conduction-direct/metadata.yaml index 6f7c35a62..d89cb3299 100644 --- a/partitioned-heat-conduction-direct/metadata.yaml +++ b/partitioned-heat-conduction-direct/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Partitioned heat conduction direct path: partitioned-heat-conduction-direct # relative to git repo url: https://precice.org/tutorials-partitioned-heat-conduction-direct.html diff --git a/partitioned-heat-conduction-overlap/metadata.yaml b/partitioned-heat-conduction-overlap/metadata.yaml index 2e5ea2404..7ebe917d9 100644 --- a/partitioned-heat-conduction-overlap/metadata.yaml +++ b/partitioned-heat-conduction-overlap/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Partitioned heat conduction overlap path: partitioned-heat-conduction-overlap # relative to git repo url: https://precice.org/tutorials-partitioned-heat-conduction-overlap.html diff --git a/partitioned-heat-conduction/metadata.yaml b/partitioned-heat-conduction/metadata.yaml index 71d18bcc5..6fbfcd5b7 100644 --- a/partitioned-heat-conduction/metadata.yaml +++ b/partitioned-heat-conduction/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Partitioned heat conduction path: partitioned-heat-conduction # relative to git repo url: https://precice.org/tutorials-partitioned-heat-conduction.html diff --git a/partitioned-pipe-multiscale/metadata.yaml b/partitioned-pipe-multiscale/metadata.yaml index c6b04ac39..83f1c2727 100644 --- a/partitioned-pipe-multiscale/metadata.yaml +++ b/partitioned-pipe-multiscale/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Partitioned pipe multiscale path: partitioned-pipe-multiscale # relative to git repo url: https://precice.org/tutorials-partitioned-pipe-multiscale.html diff --git a/partitioned-pipe-two-phase/metadata.yaml b/partitioned-pipe-two-phase/metadata.yaml index cd39f97d5..391889f29 100644 --- a/partitioned-pipe-two-phase/metadata.yaml +++ b/partitioned-pipe-two-phase/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Partitioned pipe two phase path: partitioned-pipe-two-phase # relative to git repo url: https://precice.org/tutorials-partitioned-pipe-two-phase.html diff --git a/partitioned-pipe/metadata.yaml b/partitioned-pipe/metadata.yaml index 2b92c351e..c8ac4f372 100644 --- a/partitioned-pipe/metadata.yaml +++ b/partitioned-pipe/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Partitioned pipe path: partitioned-pipe # relative to git repo url: https://precice.org/tutorials-partitioned-pipe.html diff --git a/perpendicular-flap-stress/metadata.yaml b/perpendicular-flap-stress/metadata.yaml index fbb1bbc34..409774478 100644 --- a/perpendicular-flap-stress/metadata.yaml +++ b/perpendicular-flap-stress/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Perpendicular flap stress path: perpendicular-flap-stress url: https://precice.org/tutorials-perpendicular-flap-stress.html diff --git a/perpendicular-flap/metadata.yaml b/perpendicular-flap/metadata.yaml index 5fd17c1ea..a06ec593b 100644 --- a/perpendicular-flap/metadata.yaml +++ b/perpendicular-flap/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Perpendicular flap path: perpendicular-flap url: https://precice.org/tutorials-perpendicular-flap.html diff --git a/quickstart/metadata.yaml b/quickstart/metadata.yaml index 345f41307..9a84cb2b8 100644 --- a/quickstart/metadata.yaml +++ b/quickstart/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Quickstart path: quickstart # relative to git repo url: https://precice.org/quickstart.html diff --git a/resonant-circuit/metadata.yaml b/resonant-circuit/metadata.yaml index 6988337b2..e9379af25 100644 --- a/resonant-circuit/metadata.yaml +++ b/resonant-circuit/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Resonant circuit path: resonant-circuit url: https://precice.org/tutorials-resonant-circuit.html diff --git a/tests/README.md b/tests/README.md index fd2b8d040..55ba3c0bc 100644 --- a/tests/README.md +++ b/tests/README.md @@ -320,6 +320,7 @@ Metadata and workflow/script files: - `components.yaml`: Declares the available components and their parameters/options - `reference-results-metadata.md.template`: Template for reporting the versions and machine used to generate each reference results archive - `reference_versions.yaml`: List of arguments to use for generating the reference results + - `schemas/`: JSON schemas that describe `tests.yaml`, `components.yaml`, and the `metadata.yaml` files of the tutorials - `tests.yaml`: Declares the available tests, grouped in test suites User-facing tools: @@ -350,6 +351,7 @@ Implementation scripts: Every tutorial contains a file called `metadata.yaml` describing some important properties of the tutorial. For example: ```yaml +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Elastic tube 3D path: elastic-tube-3d url: https://precice.org/tutorials-elastic-tube-3d.html @@ -390,6 +392,12 @@ Description: - `run`: Command that executes the tutorial - `component`: Component or list of components that this case depends upon (typically an adapter) +### Schemas + +The structure of `metadata.yaml`, `components.yaml`, and `tests.yaml` is described by the JSON schemas in the [`schemas/`](https://github.com/precice/tutorials/tree/develop/tests/schemas) directory. Each of these files starts with a comment of the form `# yaml-language-server: $schema=`, which makes editors that use the [YAML language server](https://github.com/redhat-developer/yaml-language-server) (e.g., the YAML extension for VS Code) offer autocompletion, show documentation on hover, and highlight mistakes while you edit. When you add a `metadata.yaml` file for a new tutorial, start it with the same comment as the existing ones. + +The same schemas are checked by the [pre-commit](https://pre-commit.com/) hooks (and therefore in the "Check style" workflow), so that a malformed entry is reported before the system tests run. If you add a new option to one of these files, also extend the respective schema. + ### Components The components mentioned in the Metadata are defined in the central `components.yaml` file. This file also specifies some arguments and their default values. These arguments can be anything, but most often they are version-related information. For example, the version of OpenFOAM used by the openfoam-adapter component, or the component version itself. For example: diff --git a/tests/components.yaml b/tests/components.yaml index 9f171c597..ef9c54a63 100644 --- a/tests/components.yaml +++ b/tests/components.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=schemas/components.schema.json bare: # A default component used when the solver does not have any dependencies apart from preCICE itself template: component-templates/bare.yaml build_arguments: # these things mean something to the docker-service diff --git a/tests/schemas/components.schema.json b/tests/schemas/components.schema.json new file mode 100644 index 000000000..cb8e2d4d5 --- /dev/null +++ b/tests/schemas/components.schema.json @@ -0,0 +1,59 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://github.com/precice/tutorials/blob/develop/tests/schemas/components.schema.json", + "title": "preCICE tutorials system tests: components.yaml", + "description": "The components (e.g., adapters, language bindings) that can be used by the cases of the tutorials, together with the parameters that their Docker image accepts.", + "type": "object", + "additionalProperties": { "$ref": "#/definitions/component" }, + "definitions": { + "component": { + "type": "object", + "additionalProperties": false, + "required": ["template", "build_arguments"], + "properties": { + "template": { + "description": "Path to the Docker Compose service template of this component, relative to the tests directory.", + "type": "string", + "minLength": 1 + }, + "repository": { + "description": "Repository of the component.", + "type": "string" + }, + "build_timeout": { + "description": "Timeout for building the Docker image of this component, in seconds.", + "type": "integer", + "minimum": 1 + }, + "build_arguments": { + "description": "The build arguments of the Docker image of this component, by name.", + "type": "object", + "additionalProperties": { "$ref": "#/definitions/buildArgument" } + } + } + }, + "buildArgument": { + "type": "object", + "additionalProperties": false, + "properties": { + "description": { + "description": "Short description of the build argument.", + "type": "string" + }, + "repository": { + "description": "Repository that a _REF build argument refers to.", + "type": "string" + }, + "default": { + "description": "Default value. Build arguments without a default value are required.", + "type": "string" + }, + "value_options": { + "description": "The values that are accepted. If not specified, all values are accepted.", + "type": "array", + "items": { "type": "string" } + } + } + } + } +} diff --git a/tests/schemas/metadata.schema.json b/tests/schemas/metadata.schema.json new file mode 100644 index 000000000..a2d338c41 --- /dev/null +++ b/tests/schemas/metadata.schema.json @@ -0,0 +1,68 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://github.com/precice/tutorials/blob/develop/tests/schemas/metadata.schema.json", + "title": "preCICE tutorials: metadata.yaml", + "description": "Metadata of a tutorial: its participants and the cases (directories) that can play the role of each participant.", + "type": "object", + "additionalProperties": false, + "required": ["name", "path", "url", "participants", "cases"], + "properties": { + "name": { + "description": "Human-readable name of the tutorial.", + "type": "string", + "minLength": 1 + }, + "path": { + "description": "Directory of the tutorial, relative to the root of the repository.", + "type": "string", + "minLength": 1 + }, + "url": { + "description": "URL of the documentation page of the tutorial.", + "type": "string", + "minLength": 1 + }, + "participants": { + "description": "The participants of the coupled simulation.", + "type": "array", + "minItems": 1, + "uniqueItems": true, + "items": { "type": "string", "minLength": 1 } + }, + "cases": { + "description": "The available cases, by name. Each case provides one participant.", + "type": "object", + "minProperties": 1, + "additionalProperties": { "$ref": "#/definitions/case" } + } + }, + "definitions": { + "case": { + "type": "object", + "additionalProperties": false, + "required": ["participant", "directory", "run", "component"], + "properties": { + "participant": { + "description": "The participant that this case provides. Must be one of the listed participants.", + "type": "string", + "minLength": 1 + }, + "directory": { + "description": "Directory of the case, relative to the tutorial directory.", + "type": "string", + "minLength": 1 + }, + "run": { + "description": "Command to run the case, executed in its directory. Leave empty (null) for cases that do not run anything, e.g., a placeholder for a participant that is not needed.", + "type": ["string", "null"], + "minLength": 1 + }, + "component": { + "description": "The component (as defined in tests/components.yaml) that this case needs.", + "type": "string", + "minLength": 1 + } + } + } + } +} diff --git a/tests/schemas/tests.schema.json b/tests/schemas/tests.schema.json new file mode 100644 index 000000000..89f0eabd0 --- /dev/null +++ b/tests/schemas/tests.schema.json @@ -0,0 +1,157 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://github.com/precice/tutorials/blob/develop/tests/schemas/tests.schema.json", + "title": "preCICE tutorials system tests: tests.yaml", + "description": "Test suites that can be triggered by the system tests. Each test suite is a list of tests, i.e., combinations of the cases of a tutorial.", + "type": "object", + "additionalProperties": false, + "required": ["test_suites"], + "properties": { + "test_suites": { + "description": "The available test suites, by name. By convention, test suites follow the name of the respective tutorial or repository, and are sorted alphabetically.", + "type": "object", + "additionalProperties": { "$ref": "#/definitions/testSuite" } + } + }, + "definitions": { + "testSuite": { + "type": "object", + "additionalProperties": false, + "anyOf": [ + { "required": ["tutorials"] }, + { "required": ["external"] } + ], + "properties": { + "tutorials": { + "description": "Tests that use tutorials from this repository.", + "type": "array", + "items": { "$ref": "#/definitions/tutorialTest" } + }, + "external": { + "description": "Tests that fetch the tutorial from an external git repository or archive.", + "type": "array", + "items": { "$ref": "#/definitions/externalTest" } + } + } + }, + "tutorialTest": { + "description": "A test of a tutorial from this repository.", + "type": "object", + "additionalProperties": false, + "required": ["path", "case_combination", "reference_result"], + "properties": { + "path": { "$ref": "#/definitions/path" }, + "case_combination": { "$ref": "#/definitions/caseCombination" }, + "reference_result": { "$ref": "#/definitions/referenceResult" }, + "max_time": { "$ref": "#/definitions/maxTime" }, + "max_time_windows": { "$ref": "#/definitions/maxTimeWindows" }, + "timeout": { "$ref": "#/definitions/timeout" }, + "tolerance": { "$ref": "#/definitions/tolerance" }, + "skip_compare": { "$ref": "#/definitions/skipCompare" }, + "run-before": { "$ref": "#/definitions/runBefore" }, + "run-after": { "$ref": "#/definitions/runAfter" } + } + }, + "externalTest": { + "description": "A test of a tutorial that is sourced from an external git repository or archive.", + "type": "object", + "additionalProperties": false, + "required": ["path", "source", "case_combination", "reference_result"], + "properties": { + "path": { "$ref": "#/definitions/path" }, + "source": { "$ref": "#/definitions/source" }, + "case_combination": { "$ref": "#/definitions/caseCombination" }, + "reference_result": { "$ref": "#/definitions/referenceResult" }, + "max_time": { "$ref": "#/definitions/maxTime" }, + "max_time_windows": { "$ref": "#/definitions/maxTimeWindows" }, + "timeout": { "$ref": "#/definitions/timeout" }, + "tolerance": { "$ref": "#/definitions/tolerance" }, + "skip_compare": { "$ref": "#/definitions/skipCompare" }, + "run-before": { "$ref": "#/definitions/runBefore" }, + "run-after": { "$ref": "#/definitions/runAfter" } + } + }, + "source": { + "description": "Where to fetch an external tutorial from.", + "type": "object", + "required": ["type", "url"], + "properties": { + "type": { + "description": "git: clone the repository at the given ref. archive: download and extract a .tar.gz / .zip.", + "enum": ["git", "archive"] + }, + "url": { + "description": "URL of the git repository or of the archive.", + "type": "string", + "minLength": 1 + }, + "ref": { + "description": "Branch or tag to check out (git only).", + "type": "string", + "minLength": 1 + }, + "subdir": { + "description": "Subdirectory of the repository or archive that contains the tutorial directory.", + "type": "string" + } + }, + "additionalProperties": false, + "if": { "properties": { "type": { "const": "git" } } }, + "then": { "required": ["ref"] } + }, + "path": { + "description": "Name of the tutorial directory (as in the path field of its metadata.yaml).", + "type": "string", + "minLength": 1 + }, + "caseCombination": { + "description": "Names of the cases (as defined in the metadata.yaml of the tutorial) that are run together, one for each participant.", + "type": "array", + "minItems": 1, + "items": { "type": "string", "minLength": 1 } + }, + "referenceResult": { + "description": "Path to the reference results archive, relative to the repository root.", + "type": "string", + "minLength": 1 + }, + "maxTime": { + "description": "Overrides the max-time of the preCICE configuration, to limit the simulated time.", + "type": "number", + "exclusiveMinimum": 0 + }, + "maxTimeWindows": { + "description": "Overrides the maximum number of time windows to simulate.", + "type": "integer", + "minimum": 1 + }, + "timeout": { + "description": "Timeout of this test, in seconds.", + "type": "integer", + "minimum": 1 + }, + "tolerance": { + "description": "Relative tolerance of the fieldcompare comparison. Defaults to 3e-7.", + "anyOf": [ + { "type": "number", "exclusiveMinimum": 0 }, + { + "description": "Numbers such as 1e-2 are loaded as strings by some YAML parsers.", + "type": "string", + "pattern": "^\\+?([0-9]+\\.?[0-9]*|\\.[0-9]+)([eE][+-]?[0-9]+)?$" + } + ] + }, + "skipCompare": { + "description": "Skip the comparison with the reference results, and only check that the build and the run succeed.", + "type": "boolean" + }, + "runBefore": { + "description": "Shell command to run in the copied tutorial directory before the Docker build.", + "type": "string" + }, + "runAfter": { + "description": "Shell command to run in the copied tutorial directory after the simulation and before the comparison.", + "type": "string" + } + } +} diff --git a/tests/tests.yaml b/tests/tests.yaml index a39616bd1..036e857a0 100644 --- a/tests/tests.yaml +++ b/tests/tests.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=schemas/tests.schema.json # Test suites that can be triggered by the system tests. # Define test suites per tutorial in the beginning of the file, # then refer to these in the release test suite and in the individual test diff --git a/turek-hron-fsi3/metadata.yaml b/turek-hron-fsi3/metadata.yaml index 1647e2120..2d8a7363d 100644 --- a/turek-hron-fsi3/metadata.yaml +++ b/turek-hron-fsi3/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Turek-Hron FSI3 path: turek-hron-fsi3 # relative to git repo url: https://precice.org/tutorials-turek-hron-fsi3.html diff --git a/two-scale-heat-conduction/metadata.yaml b/two-scale-heat-conduction/metadata.yaml index d5c748949..d2030128b 100644 --- a/two-scale-heat-conduction/metadata.yaml +++ b/two-scale-heat-conduction/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Two-scale heat conduction path: two-scale-heat-conduction url: https://precice.org/tutorials-two-scale-heat-conduction.html diff --git a/volume-coupled-diffusion/metadata.yaml b/volume-coupled-diffusion/metadata.yaml index c80aeca3f..757942fcb 100644 --- a/volume-coupled-diffusion/metadata.yaml +++ b/volume-coupled-diffusion/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Volume coupled diffusion path: volume-coupled-diffusion # relative to git repo url: https://precice.org/tutorials-volume-coupled-diffusion.html diff --git a/volume-coupled-flow/metadata.yaml b/volume-coupled-flow/metadata.yaml index d6234cf05..559539c19 100644 --- a/volume-coupled-flow/metadata.yaml +++ b/volume-coupled-flow/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Volume coupled flow path: volume-coupled-flow # relative to git repo url: https://precice.org/tutorials-volume-coupled-flow.html diff --git a/water-hammer/metadata.yaml b/water-hammer/metadata.yaml index 190287b0a..f7c1903ee 100644 --- a/water-hammer/metadata.yaml +++ b/water-hammer/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Water hammer path: water-hammer # relative to git repo url: https://precice.org/tutorials-water-hammer.html diff --git a/wolf-sheep-soil-creep/metadata.yaml b/wolf-sheep-soil-creep/metadata.yaml index 0cf1ca53d..c04bf594a 100644 --- a/wolf-sheep-soil-creep/metadata.yaml +++ b/wolf-sheep-soil-creep/metadata.yaml @@ -1,3 +1,4 @@ +# yaml-language-server: $schema=../tests/schemas/metadata.schema.json name: Wolf-sheep-grass soil creep path: wolf-sheep-soil-creep url: https://precice.org/tutorials-wolf-sheep-soil-creep.html