{"id":22273418,"url":"https://github.com/andrew-chang-dewitt/pyspec","last_synced_at":"2025-03-25T16:41:15.144Z","repository":{"id":207678224,"uuid":"170581657","full_name":"andrew-chang-dewitt/pyspec","owner":"andrew-chang-dewitt","description":"a barebones rspec style test runner for python","archived":false,"fork":false,"pushed_at":"2020-02-14T21:08:37.000Z","size":203,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-30T14:43:46.950Z","etag":null,"topics":["python-script","python3","test-driven-development","test-runner","testing","testing-tools"],"latest_commit_sha":null,"homepage":null,"language":"Python","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/andrew-chang-dewitt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2019-02-13T21:23:37.000Z","updated_at":"2023-11-17T01:04:09.000Z","dependencies_parsed_at":"2023-11-17T03:57:50.573Z","dependency_job_id":"f8832891-3c20-41c4-8ce1-e42151c5d939","html_url":"https://github.com/andrew-chang-dewitt/pyspec","commit_stats":null,"previous_names":["andrew-chang-dewitt/pyspec"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrew-chang-dewitt%2Fpyspec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrew-chang-dewitt%2Fpyspec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrew-chang-dewitt%2Fpyspec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrew-chang-dewitt%2Fpyspec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andrew-chang-dewitt","download_url":"https://codeload.github.com/andrew-chang-dewitt/pyspec/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245501751,"owners_count":20625844,"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":["python-script","python3","test-driven-development","test-runner","testing","testing-tools"],"created_at":"2024-12-03T13:12:18.957Z","updated_at":"2025-03-25T16:41:15.118Z","avatar_url":"https://github.com/andrew-chang-dewitt.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"PySpec\n======\nA barebones BDD style test runner for python \n\nLoosely inspired by RSpec, PySpec is intended for use in a behavior-driven \ndevelopment workflow (although it may work for unit testing, depending on \nyour needs). It includes a testing library \u0026 a basic CLI tool. \nPySpec is a work in progress. \n\nContents\n--------\n\n- [Installation](#installation)\n- [Quickstart](#quickstart)\n  - [Basic example](#basic-example)\n  - [Adding CLI support](#adding-cli-support)\n- [Documentation](#documentation)\n  - [Library API](/docs/lib.md)\n\nInstallation\n------------\n\nCurrently, the only installation option is through self-installation using \n`git clone` \u0026 `pip install .`. In the future, installation may be made available \nvia distribution on PyPi. \n\nTo install **PySpec**, first activate any Python vitual environment you choose (if\ndesired). Then, install from git using pip:\n\n```bash\nuser@host:~/ $ pip install git+https://github.com/andrew-dewitt/pyspec.git\n```\n\nConfirm the CLI installed correctly \u0026 is available at your path using  \n`pyspec --version`, which should return the following: \n\n```bash\nuser@host:~/ $ pyspec --version\nPySpec: version 1.1.0\n--------------------------------------------\na barebones BDD style test runner for python\n```\n\nQuickstart\n----------\n\n\nThe simplest use case is to write spec files intended to be directly called \nby python, without any support for the CLI tool.\n\n### Basic example\n\nWriting a test script begins with **describing** a test group, then \nadding tests to **it** using `describe()` \u0026 `Describe.it()`. To do this, first \nimport `describe` from `pyspec` \u0026 any modules your are testing \u0026 assign \npyspec.describe \u0026 pyspec.Comparisons some names:\n\n```python\nimport pyspec\nimport example\n\ndescribe = pyspec.describe\nC = pyspec.Comparisons\n```\n\nNext, use PySpec's `describe()` method, giving it a short description of \nthe test group, \u0026 assign it to a variable. \n\n```python\ngroup = describe('this is a test group')\n```\n\nThis returns an instance of `Describe` \u0026 assigns it to `group`. To create a \ntest, use the `it()` method from `Describe` with a short description of the \ntest as the only argument.\n\n```python\ngroup.it('this test will pass')\n```\n\nThe `it()` method returns a Test object, with an attribute `expect` that is\nused to indicate what code you are testing. `Test.expect` requires a callable\nobject as its argument, but if you need to pass only an expression or value, \nyou can simply wrap it in a `lambda`.\n\n```python\ngroup.it('this test will pass').expect(lambda: 1)          # more methods to follow ...\ngroup.it('this test will also pass').expect(some_function) # ...\n```\n\nTo state what the _expected_ value that the _actual_ passed to `Test.expect` should, \nresult in (or not result in), use `Test.to` or `Test.to_not`:\n\n```python\ngroup.it('normal testing').expect(lambda: 1).to(C.eq, 1)       # pass `eq` from `pyspec.Comparisons`\ngroup.it('negative testing').expect(lambda: 1).to_not(C.eq, 2) # use `to_not` to negate a result\n```\n\nTo test something from a module you've written, refer to it by the name you \nimported it as above, \u0026 pass the desired expression or function as your \nsecond argument to `it`. \n\n```python\ngroup.it('This test is from `example.py`').expect(example.two).to(eq, 2)\ngroup.it(\n    'Another test from `example.py`'\n).expect(\n    example.divide_by_zero\n).to(C.raise_error, ZeroDivisionError)\n```\n\nLastly, to run this example, you just need to call `Describe`'s `run()` \nmethod on `group`, like this (passing True as an argument to enable \nverbose mode):\n\n```python\ngroup.run(True)\n```\n\nThen, run this script using `$ python example_spec.py`, which will \nreturn the following:\n\n```bash\n$ python example_spec.py\n\nThis is a test group\n  - normal testing ok\n  - negative testing ok\n  - This test is from `example.py` ok\n  - Another test from `example.py` ok\n```\n\nOr you can just call `Describe.run()` with no arguments to disable \nverbose mode to return the following:\n\n```python\nThis is a test group: ok\n```\n\nDisabling verbose mode will still print any failed tests with their\nassociated stack trace.\n\nAt the end, your `example_spec.py` should look like this:\n\n```python\nimport pyspec\nimport example\n\ndescribe = pyspec.describe\nC = pyspec.Comparisons\n\ngroup = describe('this is a test group')\n\ngroup.it('normal testing').expect(lambda: 1).to(C.eq, 1)       # pass `eq` from `pyspec.Comparisons`\ngroup.it('negative testing').expect(lambda: 1).to_not(C.eq, 2) # use `to_not` to negate a result\ngroup.it('This test is from `example.py`').expect(example.two).to(eq, 2)\ngroup.it(\n    'Another test from `example.py`'\n).expect(\n    example.divide_by_zero\n).to(C.raise_error, ZeroDivisionError)\n\ngroup.run()\n```\n\nRunning tests on an `example.py`: \n\n```python\ndef two():\n    return 2\n\ndef divide_by_zero():\n    return 1 / 0\n```\n\nWith a file structure like this: \n\n```\n.\n|__ example.py\n|__ example_spec.py\n\n```\n\n### Adding CLI support\n\nTo add CLI support to the above example, only one small change needs to be\nmade: you must remove the last line, `group.run()`, of `example_spec.py` \nas `Describe.run()`will now be invoked by the CLI. Alternatively, you can\nguard the line by wrapping it in an `if` statement checking if the file\nis imported, or ran directly:\n\n```python\n...\n\nif __name__ == '__main__':\n    group.run()\n```\n\nNow, you should be able to run the spec using the CLI command `one`, \nreferring to `example_spec` in your arguments:\n\n```bash\nuser@host:~/example $ pyspec one -v example_spec\n\nThis is a test group\n  - this test will pass ok\n  - Two should be an instance of Int ok\n  - This test is from `example.py` ok\n  - Another test from `example.py` ok\n\nTests ran: 4\nSuccess rate: 100.0%\nTotal time: \u003csome number\u003e microseconds\n```\n\nGiving the `-v` or `--verbose` flag will show the individual test results\nif all tests in the group pass. Without the flag, the first line of the\nresults will instead look like `This is a test group: ok` and the lines \nfor each individual test will be supressed.\n\nAn added benefit of the CLI is that it generates some small statistics\non the test results, if you're interested. \n\n### Using the PySpec CLI\n\nThe two most general commands are `all` \u0026 `one`.\n\n#### All\n\n`$ pyspec all \u003cPATH\u003e`\n\nRuns all tests in a given directory. The argment given as `\u003cPATH\u003e` must be relative to \nthe current working directory. This command will only find files in the given \ndirectory that end in `_spec.py`.\n\n#### One\n\n`$ pyspec one \u003cMODULE\u003e`\n\nRuns the specified test file given as a module name. `\u003cMODULE\u003e` must be just the file\nname, without any file type extensions.\n\n#### List\n\n`$ pyspec list \u003cPATH\u003e`\n\nLists all `Describe` objects by their `description` for any `_spec` file found in the \ngiven \u003c`PATH`\u003e.\n\n#### See more\n\nFor more information on using the CLI, try `$ pyspec --help` for general help text \nor `$pyspec \u003ccommand\u003e --help` for more specific assistance.\n\n\nDocumentation\n-------------\n\nFor more detailed information on using the PySpec Library, see the [API Documentation](/docs/lib.md). Currently, no documentation for the CLI tool exists outside of `$ pyspec --help`, but more detailed documentation will be completed later.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrew-chang-dewitt%2Fpyspec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrew-chang-dewitt%2Fpyspec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrew-chang-dewitt%2Fpyspec/lists"}