{"id":15240466,"url":"https://github.com/ymaril/let-given","last_synced_at":"2025-04-10T13:43:03.026Z","repository":{"id":120356704,"uuid":"608597008","full_name":"Ymaril/let-given","owner":"Ymaril","description":"Well-typed context variables for testing frameworks with async functions support","archived":false,"fork":false,"pushed_at":"2023-03-26T12:24:02.000Z","size":153,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-01T12:03:16.711Z","etag":null,"topics":["let","rspec","typescript","variables"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/let-given","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ymaril.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-02T10:52:40.000Z","updated_at":"2023-10-24T11:47:27.000Z","dependencies_parsed_at":"2023-07-06T14:00:07.982Z","dependency_job_id":null,"html_url":"https://github.com/Ymaril/let-given","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ymaril%2Flet-given","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ymaril%2Flet-given/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ymaril%2Flet-given/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ymaril%2Flet-given/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ymaril","download_url":"https://codeload.github.com/Ymaril/let-given/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248226292,"owners_count":21068179,"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":["let","rspec","typescript","variables"],"created_at":"2024-09-29T11:05:08.262Z","updated_at":"2025-04-10T13:43:03.008Z","avatar_url":"https://github.com/Ymaril.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Context variables for testing frameworks\n\n[![let-given NPM version](https://badge.fury.io/js/let-given.svg)](http://badge.fury.io/js/let-given)\n\nWell-typed context variables for testing frameworks with async functions support\n\n\u003cdetails\u003e\n  \u003csummary\u003eFast example\u003c/summary\u003e\n\n  ```js\n\n  const { useGiven } = require(\"let-given\");\n\n  const { letGiven, it } = useGiven();\n\n  describe(\"User\", () =\u003e {\n    letGiven(\"user\", async ({ userParams }) =\u003e {\n      return await User.create(userParams);\n    }, [\"userParams\"])\n\n    letGiven(\"userParams\", ({ name, phone, key }) =\u003e {\n      return {\n        name: name,\n        phone: phone,\n        key: key\n      }\n    }, [\"name\", \"phone\", \"key\"]);\n\n    letGiven(\"name\", () =\u003e \"John\");\n    letGiven(\"phone\", () =\u003e \"123456789\");\n    letGiven(\"key\", async () =\u003e await (new KeyGenerator()).generate());\n\n    it(\"successful save\", ({ user, key }) =\u003e {\n      expect(user.isPersisted).toBeTruthy();\n      expect(user.name).toEqual(\"John\");\n      expect(user.phone).toEqual(\"123456789\");\n      expect(user.key).toEqual(key);\n    });\n\n    describe(\"wrong key\", () =\u003e {\n      letGiven(\"key\", () =\u003e undefined);\n\n      it(\"failed save\", ({ user }) =\u003e {\n        expect(user.isPersisted).toBeFalsy();\n        expect(user.errors).toEqual(\"Wrong key\");\n      });\n    });\n\n    describe(\"with optional field city\", () =\u003e {\n      letGiven(\"city\", () =\u003e \"London\");\n      letGiven(\"userParams\", ({ userParams, city }) =\u003e {\n        userParams.city = city;\n\n        return userParams;\n      });\n\n      it(\"successful save\", ({ user }) =\u003e {\n        expect(user.isPersisted).toBeTruthy();\n        expect(user.city).toEqual(\"London\");\n      });\n\n      describe(\"wrong city\", () =\u003e {\n        letGiven(\"city\", () =\u003e \"New York\");\n\n        it(\"failed save\", ({ user }) =\u003e {\n          expect(user.isPersisted).toBeFalsy();\n          expect(user.errors).toEqual(\"City is not located in UK\");\n        });\n      });\n    });\n  });\n\n  ```\n\u003c/details\u003e\n\n## Getting started\n\n### Installation\n\n```bash\nnpm install let-given --save-dev\n```\n\n### Usage\n\nlet-given is compatible with all popular testing frameworks([mocha][mocha], [jasmine][jasmine] and [jest][jest]). [You can also use it with other frameworks](#custom-it-wrap)\n\n```js\nconst { useGiven } = require(\"let-given\");\n\nconst { letGiven, it } = useGiven();\n\ndescribe(\"User\", () =\u003e {\n  letGiven(\"user\", ({ userParams }) =\u003e User.create(userParams), [\"userParams\"])\n  letGiven(\"userParams\", ({ name }) =\u003e ({ name }), [\"name\"]);\n\n  letGiven(\"name\", () =\u003e \"John\");\n\n  it(\"successful save\", ({ user, key }) =\u003e {\n    expect(user.isPersisted).toBeTruthy();\n    expect(user.name).toEqual(\"John\");\n  });\n});\n```\n\n#### letGiven function\n\nletGiven describes a context variable. It takes 3 parameters: variable name, variable definition function and an array of dependencies of this variable.\n```ts\nletGiven(name: string, func: (given: object) =\u003e any, dependencies: string[]);\n```\n- name - The name of the context variable. It will be used as the name of the field and in the dependency array\n- func - A function that defines a variable. The value it will return will be the value of that context variable\n- dependencies - An array of variable names on whose values this variable depends. The values of these dependencies will be passed to the func\n\n## Features\n\n### Assertation \"it\" redefine\n\nlet-given determines which test framework it works with. And returns the wrapped \"it\" functions in useGivendepending on the framework\n\n```js\n// jasmine\nconst { letGiven, it, xit, fit } = useGiven();\n// jest\nconst { letGiven, it, fit, xit, test, xtest } = useGiven();\n// mocha(it object includes fields only, skip)\nconst { letGiven, it } = useGiven();\nconst { only, skip } = it;\n```\n\nLike the original \"it\", the second argument of wrapped \"it\" function takes an assertation function. However, in the wrapped version, the given object with all the variables created by letGiven will be passed to this function as the first argument.\n\n```js\nletGiven(\"name\", () =\u003e \"John\");\nit(\"successful save\", function (given) {\n  expect(given.name).toEqual(\"John\");\n});\n```\n\n### Execute only the last variable definition\n\nlet-given will not execute functions for variables that are redefined deeper in the test suites\n\n```js\nletGiven(\"name\", async () =\u003e {\n  // this code will not execute\n  const slowNameGenerator = await slowGenerator.generateSlowNameGenerator();\n  return await slowNameGenerator.generate();\n});\ndescribe(\"with simple name\", () =\u003e {\n  letGiven(\"name\", () =\u003e \"John\");\n\n  it(\"successful save\", function (given) {\n    expect(given.name).toEqual(\"John\");\n  });\n});\n```\n[The exception is the use of super variables](#super-variables)\n\n### Full typescript support\n\nlet-given has strong typescript typing\n\n```js\n// In a typescript, you must specify a test framework\nimport useGiven from \"let-given/jasmine\"; // There are available: \"let-given/jasmine\", \"let-given/mocha\", \"let-given/jest\"\n\ninterface Given {\n  name: string,\n  userParams: object,\n  user: User\n}\n\nconst { letGiven, it } = useGiven\u003cGiven\u003e();\n\ndescribe(\"User\", () =\u003e {\n  letGiven(\"user\", ({ userParams }) =\u003e User.create(userParams), [\"userParams\"])\n  letGiven(\"userParams\", ({ name }) =\u003e ({ name }), [\"name\"]);\n\n  letGiven(\"name\", () =\u003e \"John\");\n\n  it(\"successful save\", ({ user, key }) =\u003e {\n    expect(user.isPersisted).toBeTruthy();\n    expect(user.name).toEqual(\"John\");\n  });\n});\n```\n\nThe type of each context variable is described in the interface, which is passed in the useGiven parameters. If you try to define an undeclared let-given variable, or use an undeclared variable as a dependency, the typescript will throw an error\n\n\n### Asynchronous functions\n\nYou can pass an asynchronous function to letGiven. In this case, let-given will wait for the resolution of the promise and in function  where this variable is used, the value of the result of this promise will be used.\nThis avoids await async hell in code\n\n```js\nletGiven(\"key\", async function ({ userParams }) {\n  const secret = await File.load('key.pem');\n  const keyGenerator = new KeyGenerator(secret);\n  return await keyGenerator.create();\n});\n\nit(\"successful save\", ({ key }) =\u003e {\n  expect(typeof key).toEqual('string');\n});\n```\n\n### Super variables\n\nletGiven allows you to specify the same variable as a dependency. In this case, the value of the same variable declared above in the test suite will be passed to the function\n```js\nletGiven(\"name\", () =\u003e \"John\");\ndescribe(\"with last name\", () =\u003e {\n  letGiven(\"name\", ({ name }) =\u003e `${name} Pavlov`, ['name']);\n\n  it(\"successful save\", function ({ name }) {\n    expect(name).toEqual(\"John Pavlov\");\n  });\n});\n```\n\n### Custom \"it\" wrap\n\nIf you are using a testing framework other than ([mocha][mocha], [jasmine][jasmine] and [jest][jest]), then you can use  useGivenWithWrapper to wrap any \"it\" functions\n\n```js\nconst { letGiven, test, it } = useGivenWithWrapper({\n  test: test,\n  it: it\n});\n```\nuseGivenWithWrapper will return the wrapped functions in the same fields in which they were passed in the parameters\n\n## Alternatives\n\nThere are several packages that implement context variables\n- [bdd-lazy-var](https://github.com/stalniy/bdd-lazy-var)\n- [Given2](https://github.com/tatyshev/given2)\n- [givens](https://github.com/enova/givens)\n- [jest-rspec-style](https://github.com/alfa-jpn/jest-rspec-style)\n\nSome of them have more functionality than let-given. However, they are most often badly typed. And they all don't support asynchronous functions\n\n## Benefits of using letGiven\n\nlet-given implements context variables similar to let! variables in rspec. Brings all their advantages and takes into account the specifics of javascript and typescript.\n\nThese are a few advantages of using the rspec approach for context creation:\n\n### Don't repeat yourself\n\nlet-given makes it possible to describe only that part of the context that is directly relevant to the test. No need to call fixtures or something at the beginning of each assertation\n\n### Test order\n\nRun tests in any order. Context variables exist for only one test. No more dependency on test order\n\n### No more global leaks\n\nlet-given clears variables after each test. No need to worry about clearing variables between tests\n\n### Optimal context build time\n\nDefine context variables and their dependencies. let-given take care to prepare the context as quickly as possible\n\n## Contributing\n\nYou can create issues on github with a description of the issue.\nYou can also create a pull request with fixes.\nIt is important that all tests are passed on the pull request branch.\n\nThere are two test folders: dev and dist\n- dev tests are designed to test functionality at the development stage\n- dist tests to test an already compiled distribution.\n\nRun only dev tests\n```bash\nyarn install\nyarn test\n```\n\nRun dist test\n```bash\nyarn build # build dist and copy it to node_modules\nyarn test:dist # test let-given package from node_modules folder\n```\n\n## License\n\n[MIT License](http://www.opensource.org/licenses/MIT)\n\n[mocha]: https://mochajs.org\n[jasmine]: https://jasmine.github.io/2.0/introduction.html\n[jest]: https://facebook.github.io/jest/docs/en/getting-started.html\n[contributing]: https://github.com/Ymaril/let-given/blob/master/CONTRIBUTING.md","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fymaril%2Flet-given","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fymaril%2Flet-given","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fymaril%2Flet-given/lists"}