{"id":13578188,"url":"https://github.com/ottomatica/opunit","last_synced_at":"2025-04-09T21:14:29.062Z","repository":{"id":33191393,"uuid":"147035490","full_name":"ottomatica/opunit","owner":"ottomatica","description":"🕵️‍♂️ Sanity checking containers, vms, and servers","archived":false,"fork":false,"pushed_at":"2023-03-04T02:56:04.000Z","size":4293,"stargazers_count":175,"open_issues_count":5,"forks_count":7,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-09T21:14:21.572Z","etag":null,"topics":["devops","infrastructure","infrastructure-testing","opunit","test-framework","testing"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/ottomatica.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2018-09-01T21:56:26.000Z","updated_at":"2024-06-21T20:27:38.000Z","dependencies_parsed_at":"2023-02-18T03:16:26.386Z","dependency_job_id":"14d597ea-24ed-44b4-8829-e61e1903dde9","html_url":"https://github.com/ottomatica/opunit","commit_stats":{"total_commits":440,"total_committers":12,"mean_commits":"36.666666666666664","dds":0.6681818181818182,"last_synced_commit":"d2ac7bbff3e0028dd5f25b03ce0c56e1103416d8"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ottomatica%2Fopunit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ottomatica%2Fopunit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ottomatica%2Fopunit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ottomatica%2Fopunit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ottomatica","download_url":"https://codeload.github.com/ottomatica/opunit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248111972,"owners_count":21049578,"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":["devops","infrastructure","infrastructure-testing","opunit","test-framework","testing"],"created_at":"2024-08-01T15:01:28.256Z","updated_at":"2025-04-09T21:14:29.040Z","avatar_url":"https://github.com/ottomatica.png","language":"JavaScript","readme":"# Opunit🕵️‍ | ![CI](https://github.com/ottomatica/opunit/workflows/CI/badge.svg)\nSimple tool for doing sanity checks on vms, and containers and remote servers. Written in pure node.js\n\n\n## Install with npm\n```\nnpm install ottomatica/opunit -g\n```\n\n\u003cp align=\"center\"\u003e\n\u003cimg width=\"600\" src=\"doc/img/opunit.png\"\u003e\n\u003c/p\u003e\n\n## Using Opunit\nOpunit uses a configuration file (opunit.yml) in the `/test` directory of you project. This is an example opunit.yml file. By running `opunit verify` in the root directory of your project, opunit runs the checks defined in the configuration file on the [environment of your project](#connectors); this can be a VM, container or even a remote server.\n\n``` yml\n- group:\n    description: \"Basic checks for startup\"\n    checks:\n      - availability:\n          port: 8080\n          status: 200\n          url: /\n          setup:\n            cmd: node app.js\n            wait_for: Started Application\n      - version:\n         cmd: mysql --version\n         range: ^8.x.x\n      - version:\n         cmd: node --version\n         range: ^10.x.x\n```\n\nIn this example opunit will run 3 checks. First one runs the command `node app.js` and waits for \"Started Application\", then checks the reponse status for a request to `http://{IP}/`.\nThe next two checks run `--version` commands for MySQL and Java inside the environment and compare the actual version with the provided [semver range](https://semver.org).\nIf all the checks pass, the output of opunit will look like this:\n\n```\nChecks\n\n        availability check\n        Setup: node index.js\n        Resolved wait_for condition: Stdout matches \"Started Application\"\n        Tearing down\n            ✔   [node-app] http://192.168.8.8:8080// expected: 200 actual: 200\n        version check\n            ✔   mysql --version: 8.0.12 \u003e ^8.x.x =\u003e true\n        version check\n            ✔   node --version: 10.12.0 \u003e ^10.x.x =\u003e true\n\nSummary\n\n        100.0% of all checks passed.\n        3 passed · 0 failed\n```\n\nMore examples of using Opunit can be found in Baker environments of [baker-examples](https://github.com/ottomatica/baker-examples) repository.\n\n## Checks\nOpunit has many checks available for common verification tasks. See the documentation below.\n\n`contains` supports checking contents of the file. This can be useful when there is a template file and you want to check and make sure it is updated with the correct values in the file.\n\n```yaml\n- contains:\n     file: /home/jenkins/settings/login.properties\n     string: 'username: root'\n```\n\n`status` = `true` | `false`\n\nExpected output format:\n```\ncontains check\n   ✔   [/home/jenkins/settings/login.properties] contains [username: root] status: true\n```\n\n`contains` check also supports checking value of a property in a JSON file. This check is useful for making sure a configuration file is using correct values. For example, given the JSON file below, the following check verifies `DriveName` property is set to `mysql`:\n\n```json\n{\n  \"SqlSettings\": {\n    \"DriveName\":\"mysql\"\n  }\n}\n```\n\n```yaml\n- contains: \n    file: /path/config.json\n    query: .SqlSettings.DriverName\n    string: mysql\n    expect: true\n```\n\n---\n\n`service` supports checking the status of a system service (e.g. systemd).\n\n``` yaml\n- service:\n   name: mysql\n   status: active\n- service:\n   name: shouldntexist\n   status: none\n```\n\n`status` = `active` | `inactive` | `none`\n\nExpected output:\n```\nservice check\n      ✔   [mysql] expected: active actual: active\nservice check\n      ✔   [shouldntexist] expected: none actual: none\n```\n\n---\n\n`reachable` determines whether a resource, such as a url, domain, or path is accessible from the instance. This check is good for determining whether dns or firewalls are configured appropriately.\n\n``` yaml\n- reachable:\n  - google.com\n  - nope.com/404.html\n  - reallyImportantFile.txt\n```\n\n`reachable` check also supports checking permission, group and user of a given file or directory.\n\n```yaml\n# check if file permission is set to 660\n- path: /path/file\n  permission: 660\n\n# check if group `foo` has write permission to this file\n- path: /path/file\n  permission: w\n  group: foo\n```\n\n---\n\n`capability` supports checking the environment satisfies that minimum size of memory, CPU cores, and free disk space.\n\n``` yaml\n- capability:\n    memory: 2000\n    cores: 1\n    disks:\n      - location: /\n        size: 10\n```\n\n---\n\n`availability` supports running the specified command and waiting for an output (optional), to then send a http request and check if it receives the expected status code. `or`, `||`, `and`, `\u0026\u0026` can be used to check more than one port.\n\n``` yaml\n- availability:\n    port: 3000 || 5000 || 8080\n    status: 200\n    url: /\n    timeout: 10000                        # \u003c--- optional\n    setup:                                # \u003c--- optional\n        cmd: baker run serve\n        wait_for: Started Application\n```\n\n---\n\n`version` supports running the provided `\"--version\"` command for an application on the environment, and checking if the installed version is in the range of specified semver range.\n\n``` yaml\n- version:\n    cmd: mysql --version\n    range: ^5.x.x\n```\n\n---\n\n`timezone` supports checking the timezone settings on the environment.\n\n``` yaml\n- timezone: EST\n```\n\n---\n\n`valid` check verifies the given file's format is valid. Current supported file formats are `json`, `yaml`/`yml`.\n\n```yaml\n- valid:\n    - json: /path/config.json\n    - yaml: /path/playbook.yml\n```\n\n---\n\n`env` check verifies value of an environment variable.\n\n```yaml\n- env:\n  - APP_PORT=3002\n  - MONGO_PORT=27017\n```\n\n---\n\n`jenkins_job` check can verify status of a jenkins build job. \n\n```yaml\n- jenkins_job:\n    name: myjenkinsjob\n    host: 123.123.123.123    # \u003c--- optional, will use host from connector if not provided\n    port: 1234               # \u003c--- optional, will use 8080 if not provided\n    status: success\n    user: admin\n    pass: admin\n```\n\n`status` = `success` | `failure`\n\n\u003e _Note: jenkins_job uses Jenkins api to get the job status._\n\n---\n\n`command` check can run any arbitrary command in the target environment and test it's stdout, stderr, and/or exit code against the provided values (string or [regex](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions)).\n\n```yaml\n- command: \n    exec: echo 'FOO'\n    stdout: F.*O              # \u003c--- regex or string\n    stderr: ''\n    exitCode: 0               # \u003c--- alias for exitCode: code\n\n- command: \n    exec: echo 'FOO'\n    stdout: FOO\n```\n\n\u003e _Note: We recommend you use this generic `command` check only if there are no other opunit checks for your needs. Feel free to request addition of other opunit checks by opening an issue._\n\n---\n\n## Connectors\nOpunit has different connectors to be able to run checks on different kinds of environments. See below for description of each one and how they can be used.\n\nIn general, opunit verify command looks like\n``` shell\n$ opunit verify [env_address] -c {criteria_path}\n```\n- `env_address` is used to automatically determine the type of connector for you (this is explains in more details below).\n- `criteria_path` is path to `opunit.yml` file. Opunit automatically finds this file if it is in `{current working directory}/test/opunit.yml` and in this case you don't have to provide `-c`.\n\n### ssh Connector\nIf `env_address` matches `username@host:port` format (ex. `ubuntu@127.0.0.1:2222`), then opunit will use this connector. When using this connector, you must also provide path to the ssh key:\n```\n$ opunit verify root@example.com:2222 --ssh_key ~/.ssh/id_rsa\n```\nBy default, if `port` is not provided, opunit assumes the default ssh port (22).\n\n### Baker Connector\nIf you don't specify a `env_address`, Opunit will try to use [Baker](https://github.com/ottomatica/Baker) connector by default; for example if opunit is run as below and there is a `baker.yml` file in the directory:\n``` shell\n$ opunit verify\n```\n\n### Vagrant Connector\nIf you don't specify a `env_address`, Opunit will try to use Vagrant connector by default (if it fails to find a Baker env); for example if opunit is run as below and there is a `Vagrantfile` file in the directory:\n``` shell\n$ opunit verify\n```\nAlso if `env_address` is provided and there is a running Vagrant VM with name == `env_address`, Vagrant connector will be used:\n``` shell\n$ opunit verify opunit_vagrant\n```\n\n### Docker Connector\nIf there is a running Docker container with the name or id equal to `env_address`, opunit will try to use this connector.\n```\n$ opunit verify opunit_container\n```\n\n### Local Connector\nIf `env_address` is \"local\" or \"localhost\", opunit will use local connector to run the checks on localhost.\n```\n$ opunit verify local\n```\n\n---\n\n## Inventory\n\nOpunit also supports using an inventory file to run checks on multiple (types of) environments. Inventory file is a Yaml file which lists environments that you want to check:\n\n``` yaml\n---\n- docker:\n  - name: opunit_container1\n  - name: opunit_container2\n- vagrant:\n  - name: opunit_vagrant\n- ssh:\n  - target: root@example.com\n    private_key: ~/.ssh/id_rsa\n  - target: ubuntu@example.com\n    private_key: ~/.ssh/id_rsa\n- baker:\n  - name: hibernate-spring\n    target: ~/projects/hibernate-spring\n    criteria_path: ~/projects/opunit.yml\n```\n\n**Note:** If for an environment a `criteria_path` is specified, that will be the criteria used for that environment, regardless of what is specified in `-c` or `{current working directory}/test/opunit.yml`.\n\nYou can run Opunit with an inventory file by running:\n``` shell\n$ opunit verify -i {path to inventory.yml}\n```\n\n---\n### What about inspec?\n\nInspec is a great tool! However, it requires much more verbose and manual specifications of tests.\nFor example, in inspec, a test is for checking the timezone requires writing something like this:\n\n```ruby\n# timezone should be est  \ndescribe command('date +%Z') do    \n  its(:stdout) { should match(/(EST)/) } \nend\n```\n\nIn opunit, this is simply expressed as:\n\n```yaml\n- timezone: EST\n```\n\n### Installing from Source\n\nIf you want to play with opunit's source code, we suggesting installing and running things like this:\n\n```\ngit clone https://github.com/ottomatica/opunit\ncd opunit\nnpm install\nnpm link\n```\n","funding_links":[],"categories":["JavaScript","testing"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fottomatica%2Fopunit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fottomatica%2Fopunit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fottomatica%2Fopunit/lists"}