{"id":22930304,"url":"https://github.com/smartcat-labs/ranger","last_synced_at":"2025-08-12T15:31:17.973Z","repository":{"id":43616127,"uuid":"69666299","full_name":"smartcat-labs/ranger","owner":"smartcat-labs","description":"Ranger is contextual data generator used to make sensible data for integration tests or to play with it in the database","archived":false,"fork":false,"pushed_at":"2020-05-22T12:10:08.000Z","size":702,"stargazers_count":59,"open_issues_count":14,"forks_count":11,"subscribers_count":26,"default_branch":"dev","last_synced_at":"2025-04-01T07:13:50.093Z","etag":null,"topics":["contextual-data","data-generation","data-generator","test-data"],"latest_commit_sha":null,"homepage":"https://www.smartcat.io/products/ranger-contextual-data-and-load-generator","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/smartcat-labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-09-30T12:47:28.000Z","updated_at":"2024-03-31T14:18:26.000Z","dependencies_parsed_at":"2022-09-11T21:52:37.200Z","dependency_job_id":null,"html_url":"https://github.com/smartcat-labs/ranger","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/smartcat-labs/ranger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcat-labs%2Franger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcat-labs%2Franger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcat-labs%2Franger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcat-labs%2Franger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smartcat-labs","download_url":"https://codeload.github.com/smartcat-labs/ranger/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcat-labs%2Franger/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270086565,"owners_count":24524585,"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","status":"online","status_checked_at":"2025-08-12T02:00:09.011Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["contextual-data","data-generation","data-generator","test-data"],"created_at":"2024-12-14T10:27:30.187Z","updated_at":"2025-08-12T15:31:17.671Z","avatar_url":"https://github.com/smartcat-labs.png","language":"Java","readme":"[![Build Status](https://travis-ci.org/smartcat-labs/ranger.svg?branch=master)](https://travis-ci.org/smartcat-labs/ranger)\n[ ![Download](https://api.bintray.com/packages/smartcat-labs/maven/ranger/images/download.svg) ](https://bintray.com/smartcat-labs/maven/ranger/_latestVersion)\n\n# Ranger\n\nRanger is a Java open source library that allows developers to quickly and in a simple manner define and create large number of objects whose attributes have randomly selected values from the configured set.\n\nTwo main purposes of Ranger are:\n\n- create unit and integration test data based on defined rules\n- data source for [Berserker](https://github.com/smartcat-labs/berserker)\n\nRanger can be also used as data source for a custom tool of your choice.\n\n# Quick guide\n\nQuick guide provides a way to have running Ranger example within 5 minutes from which you can start and build solution for your own needs.\nPlease take a look at [API documentation](#api) for more details what can be acomplished with Ranger.\n\n## Repository\n\nArtifact can be fetched from bintray.\nAdd following `\u003crepository\u003e` element to your `\u003crepositories\u003e` section in `pom.xml`:\n\n```xml\n\u003crepository\u003e\n  \u003cid\u003ebintray-smartcat-labs-maven\u003c/id\u003e\n  \u003cname\u003ebintray\u003c/name\u003e\n  \u003curl\u003ehttps://dl.bintray.com/smartcat-labs/maven\u003c/url\u003e\n\u003c/repository\u003e\n```\n\n## Dependency\n\nAdd the `\u003cdependency\u003e` element to your `\u003cdependencies\u003e` section in `pom.xml` with specific `version.ranger` you need:\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eio.smartcat\u003c/groupId\u003e\n  \u003cartifactId\u003eranger\u003c/artifactId\u003e\n  \u003cversion\u003e${version.ranger}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nSimilarly, dependency can be added to any other build tool supporting maven dependencies.\n\n## Code\n\nCopy the code and run it.\n\n___Example.java___\n```java\nimport static io.smartcat.ranger.BuilderMethods.*;\n\nimport java.text.ParseException;\nimport java.text.SimpleDateFormat;\nimport java.util.Date;\n\nimport io.smartcat.ranger.ObjectGenerator;\nimport io.smartcat.ranger.ObjectGeneratorBuilder;\n\npublic class Example {\n\n    private static final SimpleDateFormat DATE_FORMAT = new SimpleDateFormat(\"yyyy-MM-dd\");\n\n    public static void main(String[] args) throws ParseException {\n        ObjectGenerator\u003cAddress\u003e address = new ObjectGeneratorBuilder()\n                .prop(\"city\", random(\"New York\", \"Washington\", \"San Francisco\"))\n                .prop(\"street\", random(\"2nd St\", \"5th Avenue\", \"21st St\", \"Main St\"))\n                .prop(\"houseNumber\", random(range(1, 55))).build(Address.class);\n\n        Date januaryFifth1985 = DATE_FORMAT.parse(\"1985-01-05\");\n        Date decemberTwentySecond2000 = DATE_FORMAT.parse(\"2000-12-22\");\n\n        ObjectGenerator\u003cUser\u003e user = new ObjectGeneratorBuilder()\n              .prop(\"id\", circular(range(1L, 2_000_000L), 1L))\n              .prop(\"username\", string(\"{}{}\", random(\"aragorn\", \"johnsnow\", \"mike\", \"batman\"), random(range(1, 100))))\n              .prop(\"firstName\", random(\"Peter\", \"Rodger\", \"Michael\"))\n              .prop(\"lastName\", random(\"Smith\", \"Cooper\", \"Stark\", \"Grayson\", \"Atkinson\", \"Durant\"))\n              .prop(\"birthDate\", random(range(januaryFifth1985, decemberTwentySecond2000)))\n              .prop(\"maried\", false)\n              .prop(\"accountBalance\", random(range(0.0d, 10_000.0d)))\n              .prop(\"address\", address).build(User.class);\n\n        for (int i = 0; i \u003c 100; i++) {\n            System.out.println(user.next());\n        }\n    }\n\n    private static class Address {\n\n        public String city;\n        public String street;\n        public long houseNumber;\n\n        @Override\n        public String toString() {\n            return \"Address [city=\" + city + \", street=\" + street + \", houseNumber=\" + houseNumber + \"]\";\n        }\n    }\n\n    private static class User {\n\n        public long id;\n        public String username;\n        public String firstName;\n        public String lastName;\n        public Date birthDate;\n        public boolean maried;\n        public Double accountBalance;\n        public Address address;\n\n        @Override\n        public String toString() {\n            return \"User [id=\" + id + \", username=\" + username + \", firstName=\" + firstName + \", lastName=\" + lastName\n                    + \", birthDate=\" + birthDate + \", maried=\" + maried + \", accountBalance=\" + accountBalance\n                    + \", address=\" + address + \"]\";\n        }\n    }\n}\n\n```\n\n# Why?\n\nTotally random test data is not so useful:\n\n![Random users table](images/table-random-users.png)\n\n- It is hard to make it by certain rules\n- It is hard to reason about it\n- It does not reflect production data values nor distribution\n\nWhat we can do is use contextual data generator and create users whose attribute values make sense in the domain context. We can also say, for example, that 70% of created users should be females. The table will then look like this:\n\n![Context users table](images/table-not-so-random.png)\n\n# How it works?\n\nRanger builds a tree of dependent value generators based on user configuration (either Java API or YAML configuration). Then it uses that tree\nto construct map with generated values. If type is not specified by builder or configuration parser, `Map\u003cString, Object\u003e` is return type. If type is specified, Jackson library is used to convert map to specified type. All rules and limitations of Jackson apply here also.\n\n# API\n\nRanger supports two ways of configuring generator. [Java API](java-api.md) and [YAML Configuration](yaml-configuration.md).\n\n# Examples\n\nAll examples are located at [src/example/java](src/example/java).\n","funding_links":[],"categories":["Test Data Generation"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartcat-labs%2Franger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmartcat-labs%2Franger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartcat-labs%2Franger/lists"}