{"id":20987421,"url":"https://github.com/stacks-network/clarunit","last_synced_at":"2025-05-14T17:33:57.423Z","repository":{"id":213429578,"uuid":"734001097","full_name":"stacks-network/stacks-test-tools","owner":"stacks-network","description":"Repo for testing","archived":false,"fork":false,"pushed_at":"2024-04-05T13:51:25.000Z","size":1075,"stargazers_count":2,"open_issues_count":3,"forks_count":4,"subscribers_count":13,"default_branch":"main","last_synced_at":"2024-04-14T11:50:55.196Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stacks-network.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"2023-12-20T16:16:09.000Z","updated_at":"2024-04-18T11:50:53.664Z","dependencies_parsed_at":"2024-04-02T18:29:11.419Z","dependency_job_id":"b89b1637-996a-48a5-8b52-06ac050b7189","html_url":"https://github.com/stacks-network/stacks-test-tools","commit_stats":null,"previous_names":["stacks-network/stacks-test-tools"],"tags_count":0,"template":false,"template_full_name":"stacks-network/.github","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacks-network%2Fstacks-test-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacks-network%2Fstacks-test-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacks-network%2Fstacks-test-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacks-network%2Fstacks-test-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stacks-network","download_url":"https://codeload.github.com/stacks-network/stacks-test-tools/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225134549,"owners_count":17426235,"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":[],"created_at":"2024-11-19T06:16:54.203Z","updated_at":"2025-05-14T17:33:57.409Z","avatar_url":"https://github.com/stacks-network.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# clarunit\n\nThis package allows you to write unit tests for Clarity smart contracts in the \nClarity language itself, as opposed to TypeScript. `clarunit` will automatically\ndetect test files and test functions.\n\nAn example Clarinet-sdk project using `clarunit` can be found in the `example`\nfolder.\n\n## Setup\n\n1. Install package `@stacks/clarunit` using your favourite package manager. (Be sure to\n   pin the version!)\n2. Create a test file in your existing `tests` folder, you can use any name but\n   using `clarunit.test.ts` is recommended.\n3. Add the following to the newly created file:\n   ```ts\n   import { clarunit } from \"clarunit\";\n   clarunit(simnet);\n   ```\n4. Run your tests per usual using `npm test` or `yarn test`.\n\n`clarunit` takes configuration from Clarinet via `Clarinet.toml`. It\nautomatically detects all instantiated test contracts.\n\n## Unit testing\n\n### Adding tests\n\nTo write unit tests, follow these steps:\n\n1. Create a new Clarity contract in the `./tests` folder. It can have any name\n   but it should end in `_test.clar`. Files that do not follow this convention\n   are ignored. (For example: `my-contract_test.clar` will be included and\n   `my-contract.clar` will not.)\n2. Add the new Clarity contract to `Clarinet.toml`.\n3. Write unit tests as public functions, the function name must start with\n   `test-`.\n\n### Writing tests\n\nUnit test functions should be public without parameters. If they return an `ok`\nresponse of any kind, the test is considered to have passed whereas an `err`\nindicates a failure. The failure value is printed so it can be used to provide a\nhelpful message. The body of the unit test is written like one would usually\nwrite Clarity, using `try!` and `unwrap!` and so on as needed.\n\nExample:\n\n```clarity\n(define-public (test-my-feature)\n\t(begin\n\t\t(unwrap! (contract-call? .some-project-contract my-feature) (err \"Calling my-feature failed\"))\n\t\t(ok true)\n\t)\n)\n```\n\n### Prepare function\n\nSometimes you need to run some preparation logic that is common to all or\nmultiple unit tests. If the script detects a function called `prepare`, it will\nbe invoked before calling the unit test function itself. The `prepare` function\nshould return an `ok`, otherwise the test fails.\n\n```clarity\n(define-public (prepare)\n\t(begin\n\t\t(unwrap! (contract-call? .some-project-contract prepare-something) (err \"Preparation failed\"))\n\t\t(ok true)\n\t)\n)\n\n(define-public (test-something)\n\t;; prepare will be executed before running the test.\n)\n```\n\n### Annotations\n\nYou can add certain comment annotations before unit test functions to add\ninformation or modify behaviour. Annotations are optional.\n\n| Annotation            | Description                                                                                                                                  |\n|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------|\n| `@name`               | Give the unit test a name, this text shows up when running unit tests.                                                                       |\n| `@no-prepare`         | Do not call the `prepare` function before running this unit test.                                                                            |\n| `@prepare`            | Override the default `prepare` function with another. The function name should follow the tag.                                               |\n| `@caller`             | Override the default caller when running this unit test. Either specify an account name or standard principal prefixed by a single tick `'`. |\n| `@mine-blocks-before` | Mine a number of blocks before running the test. The number of blocks should follow the tag.                                                 |\n\nExamples:\n\n```clarity\n(define-public (prepare) (ok \"Default prepare function\"))\n\n(define-public (custom-prepare) (ok \"A custom prepare function\"))\n\n;; A test without any annotations\n(define-public (test-zero) (ok true))\n\n;; @name A normal test with a name, the prepare function will run before.\n(define-public (test-one) (ok true))\n\n;; @name This test will be executed without running the default prepare function.\n;; @no-prepare\n(define-public (test-two) (ok true))\n\n;; @name Override the default prepare function, it will run custom-prepare instead.\n;; @prepare custom-prepare\n(define-public (test-three) (ok true))\n\n;; @name This test will be called with tx-sender set to wallet_1 (from the settings toml file).\n;; @caller wallet_1\n(define-public (test-four) (ok true))\n\n;; @name This test will be called with tx-sender set to the specified principal.\n;; @caller 'ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG\n(define-public (test-five) (ok true))\n\n;; @name Five blocks are mined before this test is executed.\n;; @mine-blocks-before 5\n(define-public (test-six) (ok true))\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstacks-network%2Fclarunit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstacks-network%2Fclarunit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstacks-network%2Fclarunit/lists"}