Entry-Fixture - efix

This library is responsible for starting an EntryStore instance and loading it with contexts and entries based on a directory structure.

The fixture structure

To create a fixture simply create a folder structure that looks like:

fixtures
  - basic
    - 1.json
    - 2.json
  - repeatme_2
    - car_3.json

This structure will create three contexts in the EntryStore instance with contextIds basic, repeatme_1 and repeatme_2. The basic context will have exactly two entries with entryIds 1 and 2 while both the repeatme contexts will have three entries each with entryIds like car_1, car_2 and car_3.

To make sure each entry is created with metadata it should look like:

{
  "link": "http://example.com/ex1",
  "metadata": {
    "http://example.com/ex1": {
      "http://www.w3.org/1999/02/22-rdf-syntax-ns#type": [
         { "value": "http://www.w3.org/ns/dcat#Dataset", "type": "uri" }
      ],
      "http://purl.org/dc/terms/title": [
         { "value": "example 1", "type": "literal" }
      ]
    }
  }
}

Where the link parameter indicates the resourceURI of a link entry. If no link is provided a local entry will be created where the resourceURI is minted. For instance if the contextId is basic and entryId is 1 the minted resourceURI will be http://127.0.0.1:8282/basic/resource/1.

The metadata structure follows the RDF/JSON format. If a local entry is to be created with this format the resourecURI should be given simply as '_newId', e.g.:

{
  "metadata": {
    "_newId": {
      "http://purl.org/dc/terms/title": [
        { "value": "example 1", "type": "literal" }
      ]
    }
  }
}

Another alternative is to use a simplified metadata format where the resourceURI is not needed, i.e.:

{
  "link": "http://example.com/ex2",
  "metadata_simple": {
    "rdf:type": "U:dcat:Dataset",
    "dcterms:title": "L:example 2"
  }
}

Using the efix-start and efix-stop commands in another project

Let us assume you have another project where you need to run some tests against an entrystore instance. To achieve this you need to first add this project as a dependency in package.json:

 dependencies: {
   "@entryscape/efix": "1.0.0"
   ...
 }

Second, you need to provide a fixture folder according to above. You can call the folder anything you want, if nothing is provided as parameter it is assumed to be called fixtures.

To start the efix simply call:

yarn efix-start

To stop efix simply call:

yarn efix-stop

If you choose another name for your fixture folder, just provide that as a parameter to the efix-start command. Furthermore, you may add a third parameter with milliseconds to increase the delay before your tests can start running to give the solr index a fair chance to complete the indexing process. Hence, the commend would then be:

"pretest": "efix-start -f myfixturefolder -d 5000"

Finally, you should probably add entrystore*.log to your .gitignore file as these are automatically created log files from entrystore.

Setting up efix as part of the tests

For the test to work properly you need to run the efix-start command before your test and efix-stop after your test.

Typically this achieved as part of your test command:

"scripts": {
  "pretest": "efix-start",
  "test": "NODE_OPTIONS='--experimental-vm-modules' jest; JEST_EXIT=$?; npm run efix-stop; exit $TEST_EXIT"
}

Note that we cannot use a posttest script as that would not run if the tests fail. (The effect would be that the docker instance with the fixtures would not be stopped and the next time you run the tests it will not be a clean instance.)

Advanced options

Efix supports running entrystores in four different configurations:

• instance 1 (defailt) - http://127.0.0.1:8281/
• instance 2 - http://127.0.0.1:8281/store/
• instance 3 - http://127.0.0.1:8282/
• instance 4 - http://127.0.0.1:8282/store/

Choosing the instance to run

You simply provide the -i flag to specify which instance, e.g.:

yarn efix-start -i 3

Configuring the exposed port

These instances above correspond to how entrystore is running, i.e. how it creates URIs internally. By default it also corresponds to which port it is answering, however that can be overridden via the -p flag.

For instance, the following command will expose the entrystore on port 8080 but the URIs created internally will be with the port 8282:

yarn efix-start -i 3 -p 8080

Note that you cannot run instance 1 and 2 without providing another port as the default port for them are the same (8281), however the following is ok:

yarn efix-start -i 1 -p 8081
yarn efix-start -i 2 -p 8082

Running multiple instances

You may want to run two separate instances, e.g. instance 1 and 3 fits well together without specifying another port:

yarn efix-start
yarn efix-start -i 3

Adding the store path

If you want to run a webb application, e.g. like EntryScape on top of a fixture you will probably want to serve webbpages, scripts and css on the same port. This is accomplished with using a reverse-proxy in a webb server. This is to make sure you avoid CORS issues AND to avoid conflicting the URIs of entrystore with the webb application (which you may want to have in the root). The efix library solves this by providing the instances 2 and 4 and the configurable port. A suitable configuration for this scenario is:

# Set up the web application for port 8181
# set up a reverse proxy from :8181/store to :8280/
yarn efix-start -i 2 -p 8280

Writing tests based on efix

To write tests you need to first provide the fixture folder. Second you need to connect to the right EntryStore instance and authenticate. The efix library provides the right config for you:

import { EntryStore } from "@entryscape/entrystore-js";
import { config } from '@entryscape/efix';

const es = new EntryStore(config.repository);
es.getAuth().login(config.user, config.password).then(() => {
    // authenticated, make requests against the fixtures.
});

Furthermore, it might also be useful to load the fixtures without adding them to a EntryStore instance. This can be done via the dryRun mode:

import { EntryStore } from "@entryscape/entrystore-js";
import { efix, silent } from '@entryscape/efix';

// load the fixtures in dry run with a silent logger.
efix('fixtures', true, silent).then(({fixtures}) => {
   // fixtures corresponds to the fixture folder in the following structure:
   // {
   //    "basic1": {
   //      "http://example.com/ex1": // entry or prototypeentry instance
   //    }
   // }
});