{"id":18655677,"url":"https://github.com/knotx/knotx-junit5","last_synced_at":"2025-04-11T17:32:02.410Z","repository":{"id":47264744,"uuid":"145672629","full_name":"Knotx/knotx-junit5","owner":"Knotx","description":"JUnit 5 support and extensions for Vert.x projects","archived":false,"fork":false,"pushed_at":"2024-03-16T07:37:02.000Z","size":515,"stargazers_count":0,"open_issues_count":5,"forks_count":4,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-03-25T16:44:59.611Z","etag":null,"topics":["integration-testing","junit5","knotx"],"latest_commit_sha":null,"homepage":"https://knotx.io","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Knotx.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2018-08-22T07:27:17.000Z","updated_at":"2024-02-05T21:24:43.000Z","dependencies_parsed_at":"2024-01-27T21:24:41.988Z","dependency_job_id":"50b564dc-5f51-4718-a2a4-ad7592c1c3ef","html_url":"https://github.com/Knotx/knotx-junit5","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Knotx%2Fknotx-junit5","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Knotx%2Fknotx-junit5/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Knotx%2Fknotx-junit5/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Knotx%2Fknotx-junit5/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Knotx","download_url":"https://codeload.github.com/Knotx/knotx-junit5/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248449867,"owners_count":21105579,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["integration-testing","junit5","knotx"],"created_at":"2024-11-07T07:19:43.566Z","updated_at":"2025-04-11T17:32:01.735Z","avatar_url":"https://github.com/Knotx.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://dev.azure.com/knotx/Knotx/_apis/build/status/Knotx.knotx-junit5?branchName=master)](https://dev.azure.com/knotx/Knotx/_build/latest?definitionId=6\u0026branchName=master)\n[![CodeFactor](https://www.codefactor.io/repository/github/knotx/knotx-junit5/badge)](https://www.codefactor.io/repository/github/knotx/knotx-junit5)\n[![codecov](https://codecov.io/gh/Knotx/knotx-junit5/branch/master/graph/badge.svg)](https://codecov.io/gh/Knotx/knotx-junit5)\n[![Gradle Status](https://gradleupdate.appspot.com/Knotx/knotx-junit5/status.svg)](https://gradleupdate.appspot.com/Knotx/knotx-junit5/status)\n\n# Knot.x JUnit5\nJUnit 5 extensions and data type converters for Knot.x integration tests. Those tests allow to setup\nKnot.x instance with declared modules. It can be used both for module tests and regression tests.\n\n## Extensions\nProvides following helpers:\n\n### KnotxExtension\n\nKnot.x-specific extension that manages test Vert.x instances (with Knot.x configuration injection) \nand WireMock servers (through KnotxWiremockExtension).\n\n**Example usage:**\n\n```java\n@ExtendWith(KnotxExtension.class)\npublic class ExampleIntegrationTest {\n\n  @ClasspathResourcesMockServer(port = 4001)\n  protected WireMockServer mockRepository;\n\n  @Test\n  @KnotxApplyConfiguration({\"default.conf\", \"overloaded.conf\"})\n  public void callModule_validKnotContextResult(VertxTestContext context, Vertx vertx) {\n    // ...\n  }\n}\n```\nSee more examples in [`ExampleKnotxJUnit5Test`](https://github.com/Knotx/knotx-junit5/blob/master/src/test/java/io/knotx/junit5/examples/ExampleKnotxJUnit5Test.java).\n\nSee [Vert.x JUnit 5 integration](https://vertx.io/docs/vertx-junit5/java/) for guide\nhow to interact with `VertxTestContext` instances. Also, under `io.knotx.junit5.util.RequestUtil`\nthere are some common methods that should make working with Vert.x tests contexts easier.\n\n#### @KnotxApplyConfiguration\n\nThe annotation allows to specify one and more Knot.x configuration(s) to load for given test.\nIt accepts a paths array and loads all configuration entries using \n[Vert.x Config](https://vertx.io/docs/vertx-config/java/) file stores, through a custom \nimplementation enhanced with support for HOCON hierarchical configuration loading and cross-file\nvariable references (for more details see [KnotxConcatConfigProcessor](docs/CROSS_FILES_CONFIGURATION.md) reference). \nIt supports two configuration semantics:\n\n- JSON (files with `json` extension)\n- HOCON (files with `conf` extension)\n\nThe order of the configuration files is important, as it defines the overloading order \n(base file first, overrides last).\nFor conflicting (identical) keys in configuration, configuration entries arriving last \nwill overwrite the value provided by the previous configuration files.\n\nSee [Vert.x Config overloading rules](https://vertx.io/docs/vertx-config/java/#_overloading_rules) \nfor more details.\n\nKnotxApplyConfiguration annotation can be placed on class, method, and parameter level. As such, configuration for\nparameter level will override method and class level, and method will override class level. For quick example see\ntest package namespace `io.knotx.junit5.example`.\n\n\n#### @RandomPort\n\nIf you want to randomize a port for using inside your test, you can define a namespace inside your HOCON config:\n\n```hocon\ntest {\n  # random values generation section\n  random {\n    # all \u003cname\u003e.port entries will be substituted for different random ports\n    globalServer.port = 12345\n    actionAdapterService.port = 12345\n  }\n}\n```\n(example taken from [`example_random_config.conf`](https://github.com/Knotx/knotx-junit5/blob/master/src/test/resources/example_random_config.conf) file)\n\nThen you can reference such variables from anywhere inside your configs; placeholder values will be substituted for real available\nport numbers:\n```java\n@Test\n@KnotxApplyConfiguration(\"config/example_random_config.conf\")\npublic void injectRandomizedPort(@RandomPort Integer globalServerPort) {\n  // integer parameter will be filled with generated port from section 'random' for entry 'globalServer'\n}\n```\n\nThe working example is defined in `io.knotx.junit5.examples.ExampleKnotxJUnit5Test#injectRandomizedPort`\nmethod from test classes.\n\n### KnotxWiremockExtension\nStandalone WireMockServer injection and lifecycle management. Allows for:\n \n- Specifying on which port WireMockServer instance should be present,\n- If no port is specified on annotation, a random one will be assigned to given instance,\n- Running multiple mocked server instances,\n- Referencing mocked servers' port numbers in Knot.x configuration (more details below).\n\n***Warning:*** if you use KnotxExtension, you **must not inject** KnotxWiremockExtension, \nas the functionality of the latter gets auto-imported into the former.\n\n#### ClasspathResourcesMockServer injection and naming\n\nWireMockServer instances are recognized by their identifier - either test class instance variable name \nor test method parameter name.\n\nFor example below, two servers will be available for `testWiremockRunningOnPort` method: `mockServiceRandom` \nwith randomly assigned port, and `server` on port `3000`.\n\n```java\n@ExtendWith(KnotxWiremockExtension.class)\npublic class WireMockTest {\n\n  private static final int MOCK_SERVICE_PORT_NUMBER = 3000;\n\n  @ClasspathResourcesMockServer // will be started on a random port\n  private WireMockServer mockServiceRandom;\n\n  @Test\n  public void testWiremockRunningOnPort(\n      @ClasspathResourcesMockServer(port = MOCK_SERVICE_PORT_NUMBER) WireMockServer server)\n      throws IOException, URISyntaxException {\n    // ...\n  }\n}\n```\n\n**One exception applies:** one WireMockServer instance will be created per identifier within test given class:\n\n```java\n@ExtendWith(KnotxWiremockExtension.class)\npublic class WireMockTest {\n\n  @ClasspathResourcesMockServer\n  private WireMockServer mockServiceRandom;\n\n  @Test\n  public void testWiremockEquality(\n      @ClasspathResourcesMockServer WireMockServer mockServiceRandom) {\n    assertTrue(this.mockServiceRandom == mockServiceRandom);\n  }\n}\n```\n\nOnly one WireMockServer instance with random port is created (`mockServiceRandom`) \nand injected both into instance field and method parameter.\n\n#### Referencing WireMockServer ports in Knot.x configuration\n\nWith KnotxExtension, created WireMockServer instances' ports will be available \nfor referencing in Knot.x configuration under `test.wiremock.\u003cwiremockserver_identifier\u003e.port` variables\n(HOCON syntax only).\n\n## How to configure?\n\nFirst we need to add Knot.x Junit5 to dependencies. We can get the module version from \n[Knot.x Dependencies](https://github.com/Knotx/knotx-dependencies).\n```\ndependencies {\n  implementation(platform(\"io.knotx:knotx-dependencies:${project.version}\"))\n  testImplementation(group = \"io.knotx\", name = \"knotx-junit5\")\n  testImplementation(group = \"io.vertx\", name = \"vertx-junit5\")\n}\n```\nThe `KnotxExtension` and `KnotxWiremockExtension` use parameters names to correctly initialize \ninjected fields and parameters (see `@ClasspathResourcesMockServer`). It **requires** to compile modules with\n```\ntasks.withType(JavaCompile) {\n  options.compilerArgs \u003c\u003c \"-parameters\"\n}\n```\n\n## Frequently asked questions\n\n#### Is parallel test execution possible?\n\nCurrently not supported due to unknown Knot.x internal error that ends up in a segfault. However, all required functionality\nis implemented inside `knotx-junit5` module.\n\n#### Where can I find real examples how to use this extension?\n\nSome simple examples are available in test package namespace `io.knotx.junit5.example`.  \nFor other use cases see following Knot.x projects that use this Knot.x JUnit5 module:\n- [Knot.x Stack](https://github.com/Knotx/knotx-stack)\n- [Knot.x HTTP Server](https://github.com/Knotx/knotx-server-http)\n- [Knot.x Data Bridge](https://github.com/Knotx/knotx-data-bridge)\n\n## Utils\n\n### HoconLoader\n[HoconLoader](https://github.com/Knotx/knotx-junit5/blob/master/src/main/java/io/knotx/junit5/util/HoconLoader.java) \nparses the [HOCON](https://github.com/lightbend/config/blob/master/HOCON.md) configuration \nfiles and transforms all entries to JSON. This util is extremely helpful in \n[Routing Handler](https://github.com/Knotx/knotx-server-http/tree/master/api#routing-handlers)'s \ncontract tests.\n\n## Bugs\nAll feature requests and bugs can be filed as issues on [Gitub](https://github.com/Knotx/knotx-junit5/issues).\nDo not use Github issues to ask questions, post them on the [User Group](https://groups.google.com/forum/#!forum/knotx) or [Gitter Chat](https://gitter.im/Knotx/Lobby).\n\n## Licence\n**Knot.x modules** are licensed under the [Apache License, Version 2.0 (the \"License\")](https://www.apache.org/licenses/LICENSE-2.0.txt)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknotx%2Fknotx-junit5","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fknotx%2Fknotx-junit5","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknotx%2Fknotx-junit5/lists"}