{"id":18783913,"url":"https://github.com/sparkpost/fixture-interface","last_synced_at":"2025-12-20T20:30:15.339Z","repository":{"id":44308174,"uuid":"128383109","full_name":"SparkPost/fixture-interface","owner":"SparkPost","description":"For supplying data to tests","archived":false,"fork":false,"pushed_at":"2022-02-10T16:56:09.000Z","size":333,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":37,"default_branch":"main","last_synced_at":"2025-01-30T19:18:55.101Z","etag":null,"topics":["sp-utils"],"latest_commit_sha":null,"homepage":null,"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/SparkPost.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null}},"created_at":"2018-04-06T10:53:30.000Z","updated_at":"2022-02-10T14:22:20.000Z","dependencies_parsed_at":"2022-08-20T14:10:48.835Z","dependency_job_id":null,"html_url":"https://github.com/SparkPost/fixture-interface","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SparkPost%2Ffixture-interface","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SparkPost%2Ffixture-interface/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SparkPost%2Ffixture-interface/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SparkPost%2Ffixture-interface/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SparkPost","download_url":"https://codeload.github.com/SparkPost/fixture-interface/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239699579,"owners_count":19682574,"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":["sp-utils"],"created_at":"2024-11-07T20:41:08.895Z","updated_at":"2025-12-20T20:30:15.286Z","avatar_url":"https://github.com/SparkPost.png","language":"JavaScript","readme":"# @sparkpost/fixture-interface\n\n`fixture-interface` is, as its name implies, an interface definition for creating fixtures during tests. \nThe idea is that every fixture can create and then cleanup data for a given test before and after the test to make tests\nhighly isolated, repeatable, and stable.  This class must be extended to be used.  \nFor Long Term Support Schedule, please see: [LTS.md](/LTS.md).\n\n## Installation\n```bash\nnpm i @sparkpost/fixture-interface\n```\n\n## Getting Started\nThe fixture interface class cannot be used on its own. Its intended to be extended with an implementation specific to a \ndata source or model.  For data sources with less structure, it may be enough to create a fixture class just for the \ndata source and then pass in relevant table or indexing information upon creation to make it reusable across several \ndatabases or projects using that same database.  Elasticsearch comes to mind as an example of such a database.  \nHowever, I've found that for databases with a little more structure (SQL or partial schema NoSQL), creating a fixture\nclass for the database type and then extending that on a per table or schema basis has been most useful. Please refer to \nthe [examples directory](/example) for a fully implemented fixture example as well as executable tests using the fixture.\nThere are two examples of parent fixtures, one for an in memory store and another for AWS DynamoDB although it is not used\nin the exmaple tests. \n\n## Implementation Example\nMinimal implementation:\n```js\nconst Fx = require('@sparkpost/fixture-interface');\n\nclass MyFx extends Fx {\n  insert(item) {\n    return Promise.resolve();\n  }\n\n  remove(key) {\n    return Promise.resolve();\n  }\n}\n\nmodule.exports = MyFx;\n```\nThe only requirements of implementation are that the `insert` and `remove` functions be implemented and that these \nfunctions return a promise.  Within these functions we'll want to define the rules for inserting data into or removing \ndata from our database respectively.\n\nAn example of inserting or removing items in AWS DynamoDB may look like:\n```js\nclass DynamoFx extends Fx {\n\n  constructor(connConfig, tableName) {\n    super();\n\n    this.tableName = tableName;\n\n    // setup dynamo connection info\n    this.db = new Aws.DynamoDB.DocumentClient(connConfig);\n  }\n  \n  makeKey(item){\n    throw new Error(`'makeKey' must be implmented in your DyanmoDB data fixture`);\n  }\n\n  insert(item) {\n    return this.db.put({TableName: this.tableName, Item: item}).promise();\n  }\n\n  remove(item) {\n    return this.db.delete({TableName: this.tableName, Key: this.makeKey(item)}).promise();\n  }\n}\n```\nThis particular fixture must also be extended as it requires the `makeKey` method to be implemented.  Since DynamoDB's \npartition keys are specific to each of its tables, this makes reusing this fixture across different tables fairly easy.\n\n## Execution Example\nAt this point using your fixture is pretty easy. Instantiate it, pass it some data, and when your tests are done, clean \nit up.\n\n_This example is written using Jest but the fixture usage is completely independent of test runners._ \n```js\ndescribe('Basic Test', () =\u003e {\n  let myFx;\n\n    beforeAll(() =\u003e {\n      // provisions data from a json file\n      return myFx.provision(require('./data.json')) \n    });\n    \n    afterAll(() =\u003e {\n      return myFx.cleanup();\n    });\n    \n    it('should be asserting some db operation', () =\u003e {\n      // expect something here\n    });\n});\n```\nThats it.  The `provision` method uses the `insert` method above we defined earlier to insert each item into the database.  \nThe `cleanup` method takes advantage of `remove`.\n\n### Keeping Tests Independent for C~~RU~~D Operations\nThere may come a time where the database operation that you're testing is simply deleting data from the database.  \nThis is pretty easy to account for since you can just provision data with your fixture, delete it during your test and \nassert that its gone.  The cleanup function will try to delete that data however most databases will silently ignore a \ndelete call for something that isn't there.  If not, your `remove` implementation may have to account for this.\n\nWhen testing creation operations it ends up being a little different.  You can manage cleaning up any created data \nyourself, however your fixture has a method called `alsoRemove` and this comes in handy if you want to keep your tests\nstreamlined.  Once your test creates some data, you can call `alsoRemove` by passing it an item of the same format in \nyour provisioning step to remove said item.  Your new item will be removed along with other provisioned data during the \ncleanup execution. This keeps your tests focused on testing without too much worry about data management.\n\n```js\n  it('should create an item', () =\u003e {\n    const item = {key: 1, data:\"string\"};\n    return model.create(item).then(()=\u003e{\n      myFx.alsoRemove(item);\n      // expect something here\n    })\n  });\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsparkpost%2Ffixture-interface","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsparkpost%2Ffixture-interface","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsparkpost%2Ffixture-interface/lists"}