{"id":13658735,"url":"https://github.com/dollarshaveclub/study","last_synced_at":"2025-04-04T18:08:02.188Z","repository":{"id":35401085,"uuid":"39665367","full_name":"dollarshaveclub/study","owner":"dollarshaveclub","description":"A simple, progressive, client/server AB testing library 📚 ","archived":false,"fork":false,"pushed_at":"2022-06-08T00:23:50.000Z","size":271,"stargazers_count":314,"open_issues_count":6,"forks_count":13,"subscribers_count":45,"default_branch":"master","last_synced_at":"2024-05-09T14:26:49.823Z","etag":null,"topics":["ab-testing","bucket","client","drivers","experiment","server","test"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/dollarshaveclub.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-07-25T00:21:20.000Z","updated_at":"2024-04-16T20:34:04.000Z","dependencies_parsed_at":"2022-09-11T06:50:59.806Z","dependency_job_id":null,"html_url":"https://github.com/dollarshaveclub/study","commit_stats":null,"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dollarshaveclub%2Fstudy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dollarshaveclub%2Fstudy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dollarshaveclub%2Fstudy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dollarshaveclub%2Fstudy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dollarshaveclub","download_url":"https://codeload.github.com/dollarshaveclub/study/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247226215,"owners_count":20904465,"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":["ab-testing","bucket","client","drivers","experiment","server","test"],"created_at":"2024-08-02T05:01:02.147Z","updated_at":"2025-04-04T18:08:02.169Z","avatar_url":"https://github.com/dollarshaveclub.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"\u003ca href=\"https://github.com/dollarshaveclub/study\"\u003e\n  \u003cimg src=\"https://dollarshaveclub.github.io/study/assets/study-v2.svg\"\u003e\n\u003c/a\u003e\n\n\u003e A progressive, client/server AB testing library.\n\n[![CircleCI](https://circleci.com/gh/dollarshaveclub/study/tree/master.svg?style=svg)](https://circleci.com/gh/dollarshaveclub/study/tree/master)\n[![codecov](https://codecov.io/gh/dollarshaveclub/study/branch/master/graph/badge.svg)](https://codecov.io/gh/dollarshaveclub/study) [![Greenkeeper badge](https://badges.greenkeeper.io/dollarshaveclub/study.svg)](https://greenkeeper.io/)\n[![npm][npm-image]][npm-url]\n[![bower][bower-image]][bower-url]\n\n[npm-image]: https://badge.fury.io/js/studyjs.svg\n[npm-url]: https://www.npmjs.com/package/studyjs\n[bower-image]: https://badge.fury.io/bo/study.svg\n[bower-url]: https://github.com/dollarshaveclub/study\n\nStudy is an AB testing library designed to be clear, minimal, and flexible. It works in both the server and browser with the use of driver-based persistence layers.\n\nYou can download the compiled javascript directly [here](/build/study.js)\n\n* [Features](#features)\n* [Installing](#installing)\n* [Usage](#usage)\n* [API](#api)\n* [Guide/FAQ](#guidefaq)\n* [License](#license)\n\n***\n\n## Features\n\n* Powerful, clear API\n* Many variations. ABCD testing\n* Intelligent weighted bucketing\n* Browser \u0026 Server support\n* Storage Drivers: `localStorage`, `cookies`, `memory`, or build your own\n* Well documented, tested, and proven in high production environments\n* Lightweight, weighing in at ~ \u003cspan class=\"size\"\u003e`3.8kb`\u003c/span\u003e.\n* Not tested on animals\n\n## Installing\n\n```bash\n# Via NPM\nnpm i studyjs --save\n\n# Via Bower\nbower i studyjs --save\n\n# Via Yarn\nyarn add studyjs\n```\n\n## Developing\n\n```bash\nnpm install # Install dependencies\nnpm build # Build the babel'd version\nnpm lint # Run linting\nnpm test # Run tests\n```\n\n## Usage\n```html\n\u003cscript src=\"study.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n\n  // Set up our test API\n  const test = new Study({\n    store: Study.stores.local\n  });\n\n  // Define a test\n  test.define({\n    name: 'new-homepage',\n    buckets: {\n      control: { weight: 0.6 },\n      versionA: { weight: 0.2 },\n      versionB: { weight: 0.2 },\n    }\n  });\n\n  // Bucket the user\n  test.assign();\n\n  // Fetch assignments at a later point\n  const info = test.assignments();\n\u003c/script\u003e\n```\n\n## API\n\n\u003e ## `Study(config)`\n\n```javascript\nconst study = new Study({\n  debug: true,\n  store: Study.stores.local\n});\n```\n\u003e This creates a new test API used to defined tests, assign buckets, and retrieve information.\n\n**Returns**: `Object`\n\nName | Type | Description | Default\n:--- | :--- | :--- | :---\n`debug` | `Boolean` | _Set to `true` to enable logging of additional information_ | `false`\n`store` | `Object` | _An object with get/set properties that will accept information to help persist and retrieve tests_ | `Study.stores.local`\n\n***\n\n\u003e ## `study.define(testData)`\n\n```javascript\n// Create your test API\nconst study = new Study();\n\n// Define a test\nstudy.define({\n  name: 'MyTestName',\n  buckets: {\n    variantA: { weight: 0.5 },\n    variantB: { weight: 0.5 },\n  },\n});\n```\n\u003e This function defines the tests to be assigned to used during bucket assignment. This function accepts an object with two keys, `name` and `buckets`. Alternatively, you may pass an array of similar objects to define multiple tests at once.\n\n\u003e The `name` value is the name of your test. The keys within `bucket` are your bucket names. Each bucket value is an object containing an object with an optional key `weight` that defaults to `1`.\n\n\u003e The percent chance a bucket is chosen for any given user is determined by the buckets weight divided by the total amount of all weights provided for an individual test. If you have three buckets with a weight of 2, `2/6 == 0.33` which means each bucket has a weight of `33%`. There is no max for the total weights allowed.\n\n**Returns**: `null`\n\nName | Type | Description | Default\n:--- | :--- | :--- | :---\n`data` | `Object/Array` | _An object/array of objects containing test and bucket information_ | `null`\n\n***\n\n\u003e ## `study.assign(testName, bucketName)`\n\n```javascript\nconst study = new Study();\nstudy.define({\n  name: 'new-homepage',\n  buckets: {\n    variantA: { weight: 0.5 },\n    variantB: { weight: 0.5 },\n  }\n});\n\n// Assign buckets from all tests to the user...\nstudy.assign();\n\n// or assign bucket from the specified test...\nstudy.assign('new-homepage');\n\n// or specify the bucket from the specified test...\nstudy.assign('new-homepage', 'variantB');\n\n// or remove the bucketing assignment from the specified test.\nstudy.assign('new-homepage', null);\n```\n\u003e Calling the `assign` method will assign a bucket for the provided tests to a user and persist them to the `store`. If a user has already been bucketed, they will _not_ be rebucketed unless a `bucketName` is explicitly provided.\n\n\u003e If no arguments are provided, all tests will have a bucket assigned to the user. If the first argument provided is a test name, it will attempt to assign a bucket for that test to a user. If a `bucketValue` is provided, it will set that user to the specified bucket. If the `bucketValue` is null, it will remove that users assignment to the bucket.\n\n**Returns**: `null`\n\nName | Type | Description | Default\n:--- | :--- | :--- | :---\n`testName` (optional) | `String` | _The name of the test to assign a bucket to_ | `null`\n`bucketName` (optional) | `String` | _The name of the bucket to assign to a user_ | `null`\n\n***\n\n\u003e ## `study.definitions()`\n\n```javascript\nconst study = new Study();\nstudy.define({\n  name: 'new-homepage',\n  buckets: {\n    variantA: { weight: 0.5 },\n    variantB: { weight: 0.5 },\n  }\n});\n\n// Retrieve all of the provided tests\nconst tests = study.definitions();\n```\n\u003e This provides the user with all of the tests available.\n\n\u003e The returned information will be an array if multiple tests were defined, otherwise, it will be an object of the single test defined. The object will mirror exactly what was provided in the `define` method.\n\n**Returns**: `Object|Array`\n\n***\n\n\u003e ## `study.assignments()`\n\n```javascript\nconst study = new Study();\nstudy.define({\n  name: 'new-homepage',\n  buckets: {\n    variantA: { weight: 1 },\n  }\n});\n\n// Capture assignments\nstudy.assign();\n\n// Retrieve all of the bucket assignments for the user\nconst buckets = study.assignments();\nassert.strictEqual(buckets['new-homepage'], 'variantA');\n```\n\u003e This provides the user with all of the bucket assignments for the current user.\n\n\u003e The returned information will be an object whose keys will be test names and values will be the current bucket assigned to the user.\n\n```javascript\n// Example return\n{\n  'new-homepage': 'variantA',\n  'some-test': 'some-bucket',\n}\n```\n\n**Returns**: `Object|Array`\n\n***\n\n\u003e ## `study.extendAssignments`\n\u003e Extending assignments can be a useful way to augment your Study implementation with third party software.\n\n```javascript\nconst study = new Study();\n\n// Create a function that will modify assignments before you call `assignments`\nstudy.extendAssignments =\n  (assignments) =\u003e Object.assign(assignments, { foo: 'bar' })\n\n// Retrieve all of the bucket assignments for the user\nconst buckets = study.assignments();\nassert.strictEqual(buckets['foo'], 'bar');\n```\n\u003e A more practical example could be to implement with a third party AB testing platform like Optimizely _(This uses pseudo code for brevity)_\n\n```javascript\nstudy.extendAssignments = (assignments) =\u003e {\n  if (window.optimizely)\n    for (const experiment in optimizely.experiments())\n      assignments[experiment.name] = experiment.bucket\n\n  return assignments\n}\n```\n\n**Returns**: `Object`\n\n\n***\n\n## Guide/FAQ\n\n### CSS Driven Tests\nTests logic may be potentially powered on solely CSS. Upon calling `assign`, if the script is running in the browser, a class per test will be added to the `body` tag with the test name and bucket in `BEM` syntax.\n```html\n\u003cbody class=\"new-homepage--variantA\"\u003e \u003c!-- Could be new-homepage--variantB --\u003e\n```\n```css\n.new-homepage--variantA {\n  /* Write custom styles for the new homepage test */\n}\n```\n\n### Storing metadata associated with tests\nEach bucket provided may have additional metadata associated with it, and may have its value retrieved by retrieving the assignments and definitions.\n```javascript\nconst study = new Study();\nstudy.define({\n  name: 'new-homepage',\n  buckets: {\n    variantA: { weight: 1, foo: 'bar' },\n  }\n});\n\nstudy.assign();\n\nconst defs = study.definitions();\nconst buckets = study.assignments();\nconst bucket = buckets['new-homepage'];\nconst bar = defs.buckets[bucket].foo; // \"bar\"\n```\n\n## License\n\n**MIT Licensing**\n\nCopyright (c) 2015 - 2018 Dollar Shave Club\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdollarshaveclub%2Fstudy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdollarshaveclub%2Fstudy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdollarshaveclub%2Fstudy/lists"}