{"id":36419266,"url":"https://github.com/servirtium/servirtium-java","last_synced_at":"2026-01-11T17:02:37.384Z","repository":{"id":37867422,"uuid":"156706507","full_name":"servirtium/servirtium-java","owner":"servirtium","description":"Service Virtualized HTTP - to help service test automation stay fast and consistent","archived":false,"fork":false,"pushed_at":"2023-03-10T01:59:38.000Z","size":1047,"stargazers_count":18,"open_issues_count":9,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-07-24T09:45:04.791Z","etag":null,"topics":["mock-server","mocking-framework","service-virtualization","servirtium","tck","test-automation","test-doubles","testing-tools"],"latest_commit_sha":null,"homepage":"https://servirtium.dev/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/servirtium.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-11-08T12:51:22.000Z","updated_at":"2024-08-09T09:09:40.000Z","dependencies_parsed_at":"2023-02-17T12:50:17.526Z","dependency_job_id":null,"html_url":"https://github.com/servirtium/servirtium-java","commit_stats":null,"previous_names":["paul-hammant/servirtium"],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/servirtium/servirtium-java","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/servirtium%2Fservirtium-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/servirtium%2Fservirtium-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/servirtium%2Fservirtium-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/servirtium%2Fservirtium-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/servirtium","download_url":"https://codeload.github.com/servirtium/servirtium-java/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/servirtium%2Fservirtium-java/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28314260,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-11T14:58:17.114Z","status":"ssl_error","status_checked_at":"2026-01-11T14:55:53.580Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["mock-server","mocking-framework","service-virtualization","servirtium","tck","test-automation","test-doubles","testing-tools"],"created_at":"2026-01-11T17:02:37.319Z","updated_at":"2026-01-11T17:02:37.376Z","avatar_url":"https://github.com/servirtium.png","language":"Java","readme":"# Servirtium\n\n![](Servirtium-Square.png?raw=true)\n\nServirtium == Service Virtualized HTTP (for Java) in a record/playback style, with plain \nMarkdown recordings\n\nUtilization of \"Service Virtualization\" is best practice towards fast and \nconsistent test automation. This tech should be used in conjunction with \nJUnit/TestNG, etc.  Versus alternate technologies, Servirtium utilizes Markdown\nfor recorded HTTP conversations, which aids readability allows for diffing \nto quickly determine if contracts are broken. That last is an important aspect\nwhen Service Virtualization is part of a **Technology Compatibility Kit**\n\n## Design goals \n\n1. By being a \"man in the middle\" it enables the recording of HTTP conversations and store them in Markdown under \nsource-control co-located with the automated tests themselves. \n2. In playback, Servirtium allows the functionality tested in the service tests to be isolated from potentially flaky \nand unquestionably slower \"down stack\" and external remote services.\n3. A diffable format (regular Markdown files) to clearly show the differences between two recordings of the same \nconversation, that is co-located with test logic (no database of any sort)\n4. Agnostic about other test frameworks: use JUnit 4, JUnit5, TestNG, Cucumber for Java, or JBehave.\n5. No process spawning/killing orchestration.\n6. One recording per test method, even if that means duplicate sections of markdown over many tests\n7. No conditionals or flow control in the recording - no DSL at all. \n8. Allowance for modification of recording or playback for simplification/redaction purposes.\n9. For use **in the same process** as the test-runner. It is not designed to be a \nstandalone server, although it can be used that way.\n\n## Design Limitations\n\n1. Just for Java teams presently (needs porting)\n3. Not for playback use in \"for humans\" environments like QA or UAT\n\n## What do recordings look like?\n\n### Raw recording source (Markdown)\n\nHere's a shorted source form for a recorded conversation\n\n![](https://user-images.githubusercontent.com/82182/66556432-21473c00-eb48-11e9-8fb3-06259d79ff2b.png)\n\n### Rendered Markdown in the GitHub UI\n\nBest to see a real one here [in situ on GitHub](https://github.com/paul-hammant/climate-data-tck/blob/master/src/test/mocks/averageRainfallForEgyptFrom1980to1999Exists.md) \nrather than the minimal example above. You can see the rendering there (best for human eyes), but also a snap-shot of \nthat here:\n\n![](https://user-images.githubusercontent.com/82182/66568199-df76bf80-eb60-11e9-83a8-61be277a9fae.png)\n\n### More info\n\nSee [ExampleSubversionCheckoutRecording.md](https://github.com/paul-hammant/servirtium/blob/master/src/test/resources/ExampleSubversionCheckoutRecording.md) \nwhich was recorded from a real Subversion 'svn' command line client doing it's thing, but \nthru Servirtium as a HTTP-proxy. After the recording of that, the replay side of Servirtium was able \nto pretend to be Apache+Subversion for a fresh 'svn checkout' command. \n[This one](https://github.com/paul-hammant/servirtium/blob/master/src/test/java/com/paulhammant/servirtium/SubversionCheckoutRecorderMain.java) \nwas the recorder, and [this one](https://github.com/paul-hammant/servirtium/blob/master/src/test/java/com/paulhammant/servirtium/SubversionCheckoutReplayerMain.java) \nthe replayer for that recorded conversation.\n\n## Implementation Limitations\n\n1. Java only for now, though usable in the broader JVM ecosystem. Ports to other languages \nis a direction I'd like to go in. Perhaps a rewrite in Rust, and then bindings back to Java, C#, \nPython, Ruby and NodeJs would be a more sustainable route long term.\n\n2. The recorder **isn't very good at handling parallel requests**. Most of the \nthings you want to test will be serial (and  short) but if your client is a browser, \nthen you should half expect for parallelized operations.\n\n3. Servirtium can't yet listen on over HTTPS.\n\n4. Servirtium can't yet function as a HTTP Proxy server. It must be a \"man in the middle\", \nmeaning you have to be able to override the endpoints of services during JUnit/TestNG invocation \nin order to be able to record them (and play them back).\n \n5. Some server technologies (like Amazon S3) sign payloads in a way that breaks for middle-man \ndeployments. See [S3](https://github.com/paul-hammant/servirtium/wiki/S3).\n \n# Notable examples of use\n\n## SvnMerkleizer project - emulation of Subversion in tests\n\n[Read more about two seprate uses of Servirtium for this project](docs/SvnMerkleizer_More_Info.md)\n\n## Climate API demo\n\nThe World Bank's Climate Data service turned into a Java library with Servirtium tests: \nhttps://github.com/paul-hammant/climate-data-tck. Direct, record and playback modes of \noperation for the same tests.\n\n## Todobackend record and playback\n\n[TodobackendDotComServiceRecording.md](https://github.com/paul-hammant/servirtium/blob/master/src/test/resources/TodobackendDotComServiceRecording.md) \nis a recording of the Mocha test site of \"TodoBackend.com\" against a real Ruby/Sinatra/Heroku \nendpoint. This is not an example of something you'd orchestrate in Java/JUnit, but it is \nan example of a sophisticated series of interactions over HTTP between a client (the browser) \nand that Heroku server. Indeed, the intent of the site is show that multiple backends should be\ncompatible with that JavaScript/Browser test suite.\n\n[Here's the code for the recorder](https://github.com/paul-hammant/servirtium/blob/master/src/test/java/com/paulhammant/servirtium/SubversionCheckoutRecorderMain.java) \nof that, and [here's the code for the replayer](https://github.com/paul-hammant/servirtium/blob/master/src/test/java/com/paulhammant/servirtium/SubversionCheckoutReplayerMain.java)\nfor that.  \n\nNote: playback does not pass all the tests because there's a randomized GUID in the request \npayload that changes every time you run the test suite. It gets one third of the way through though.\n\n**Note: this limitation is being resolved, presently**\n\n## Readiness for general industry by lovers of test automation?\n\nA pre 1.0 release is used by a startup Paul is involved with for multiple unrelated external services.\n\n## Servirtium's default listening port\n\nAs per [the default port calculator](https://paul-hammant.github.io/default-port-calculator/#servirtium) for 'servirtium': 61417 \n\n# Further Wiki Documentation\n\n[Servirtium in Technology Compatibility Kits](../../wiki/Servirtium-in-Technology-Compatibility-Kits)\n[Adding-notes-to-a-recording](../../wiki/Adding-notes-to-a-recording)\n\n# Building Servirtium\n\nThis builds the binaries, but skips integration tests as they rely on Wikipedia, Reddit \nand others which are moving targets sometimes.\n\n```\nmvn clean install\n```\n\nThis builds the binaries, and includes integration tests (that use various services on the web)\n\n```\nmvn clean install -Ptests\n```\n\n## License\n\nBSD 2-Clause license (open source). Refer to [LICENSE.txt](/paul-hammant/servirtium/blob/master/LICENSE.txt)\n\n## Legal warning\n\nBe careful: your contracts and EULAs with service providers \n(as well as application/server makers for on-premises) might not allow you to \nreverse engineer their over-the-wire APIs.  \n\nA real case: [Reverse engineering of competitor’s software cost company big](http://blog.internetcases.com/2017/10/24/reverse-engineering-of-competitors-software-cost-company-big/) - and you might say that such clauses are needed to prevent licensees from competing with the original company with arguably \"stolen\" IP. \n\nWe (developers and test engineers) might morally think that we should be OK for this, as we're just doing it for \ntest-automation purposes. No matter, the contracts that are signed often make no such distinction, but \nthe case above was where the original maker of an API went after a company that was trying to make \nsomething for the same ecosystem without a commercial relation on that specifically.\n\n## Code of Conduct\n\nBe Nice (in lieu of something longer)","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fservirtium%2Fservirtium-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fservirtium%2Fservirtium-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fservirtium%2Fservirtium-java/lists"}