@entryscape/efix

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 resoureURI 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"
  }
}

If you want to create a linkreference entry with both a local metadata and cached external metadata you do the following:

{
  "link": "http://example.com/ex4",
  "metadata_link": "http://example.com/metadata/ex4",
  "metadata_simple": {
    "dcterms:title": "L:example 4 local"
  },
  "cached_metadata_simple": {
    "rdf:type": "U:dcat:Dataset",
    "dcterms:title": "L:example 4 cached"
  }
}

Note that the example above used the simplified format for metadata, it is also possible to use the RDF/JSON format by using the key cached_metadata.

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. Hence, the commend would then be:

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

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 (entrystore baseurl and port exposed on):

• instance 1 (default) - http://127.0.0.1:8281/ on port 8281
• instance 2 - http://127.0.0.1:8282/ on port 8282
• instance 3 - http://127.0.0.1:8281/store/ on port 8283
• instance 4 - http://127.0.0.1:8282/store/ on port 8284

Choosing the instance to run

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

yarn efix-start -i 3

Running multiple instances

You may want to run two separate instances, but make sure they run on separate ports. E.g. instance 1 and 2 fits well together as well as instance 3 and 4:

yarn efix-start
yarn efix-start -i 2

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 3 and 4 and the configurable port. A suitable configuration for instance 3 is:

# Before the efix-start YOU HAVE TO SET UP:
# 1. the web application for port 8181 (anything NOT under /store)
# 2. set up a reverse proxy from :8181/store to :8283/ where the entrystore is runnn
yarn efix-start -i 3

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 an 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
   //    }
   // }
});