Skip to content

Latest commit

 

History

History
169 lines (119 loc) · 8.64 KB

contribution.md

File metadata and controls

169 lines (119 loc) · 8.64 KB
Raw

Contribution

How to Contribute to this Project

If you are interested in contributing to this project, please read our general contribution guidelines first.

Introduction

The purpose of this library is to facilitate the use of DSP-API (Knora) in web client development. It offers a convenient way to communicate with DSP-API without knowing specific technical details.

Architecture

See design documentation.

Development

Prerequisites

For development, you need to install yalc globally. Run npm install yalc -g. This will enable you to build and publish DSP-JS-LIB locally.

Dependencies

This library depends on RxJS, jsonld, and json2typescript. jsonld and json2typescript are only used internally and listed as dependencies in package.json.

RxJS is listed as a peer dependency and not installed with npm install. It can be installed running npm run peer-deps after npm install.

RxJS's Observable is used in this library's public API and has to be compatible with whatever version of RxJS is used in the productive environment, e.g. an Angular application. This library works with RxJS's major version defined in package.json. See Use of RxJS for details.

Scripts for Testing and Development

This package provides the following short-hand scripts:

  1. npm run peer-deps: Installs the project's peer dependencies. Peer dependencies are not installed with npm install, but have to be met before building or running the tests.
  2. npm run test: Runs the library's tests defined in ./karma.conf.js.
  3. npm run prepare-dev-publication: prepares a dev version of the library before building it. The dev version contains code to create mocked data to be used in unit tests of projects using DSP-JS-LIB.
  4. npm run build: Builds the whole library without testing and puts the files into the ./build/ folder.
  5. npm run yalc-publish: Builds and publishes the package to the yalc app store (local publication of the lib).
  6. npm run yalc-publish-and-update: Builds and publishes the package to the yalc app store (local publication of the lib) and updates any local repositories using the package with this newly created package.
  7. npm run npm-pack: Tests and builds the library and then packs the ./build/ folder into an NPM tgz package. The package is moved into a ./dist/ folder.

Build and Publish a Local Version

Using yalc, DSP-JS-LIB can be built and published locally:

  • Run npm install and npm run peer-deps
  • Run npm run prepare-dev-publication if the mocks should be included, see section below.
  • Run npm run yalc-publish

Alternatively, you can run npm run build-local which combines the script mentioned above.

Development Version

The development version contains mocks that produce tests data without a connection to DSP-API. These mocks were originally developed for internal use, but can be used to get data for unit tests in projects that use DSP-JS-LIB. The following example shows how to get a mocked resource without a connection to DSP-API:

import { MockResource } from "@dasch-swiss/dsp-js";

MockResource.getTestThing().subscribe(
    (testthing: ReadResource) => {
        console.log(testthing);
    }
)

The mocks are configured in scripts/mock-exports.json.

If you need a local version of this library that contains the mocks, do the following:

  • npm run prepare-dev-publication to prepare a dev version.
  • npm run yalc-publish to publish a local build containing the mocks.

Note that prepare-dev-publication modifies package.json, tsconfig.json and index.ts. Run this script only once and do not commit these changes.

Integrating Generated Test Data from DSP-API

Unit tests use data that is generated by DSP-API.

Download test data generated by DSP-API by running make get-test-data-from-release. This will download the test data for DSP-API release which is set in vars.mk.

To integrate test data generated by DSP-API, the following scripts can be used. Instead of running these scripts one by one, you can also run make prepare-test-data.

  1. npm run integrate-system-test-data <path-to-generated-client-code>: integrates generated test data for DSP-API system API.
  2. npm run integrate-admin-test-data <path-to-generated-client-code>: integrates generated test data for DSP-API admin API.
  3. npm run integrate-v2-test-data <path-to-generated-client-code>: integrates JSON-LD test data for DSP-API v2 API.
  4. npm run expand-jsonld-test-data: creates versions with expanded prefixes for DSP-API v2 JSON-LD test data.

By default, all generated test data for the system and admin API is integrated with the corresponding script.

Test data for v2 has to be added to scripts/v2-test-data-config.json to be used in the unit tests. source refers to their location in DSP-API test data directory structure, destination refers to their location in this repo. All files that are listed in scripts/v2-test-data-config.json will be copied to this library's test data directory when running npm run integrate-v2-test-data.

Example:

{
  "generated-test-data": [
    {
      "source": "/v2/ontologies/all-ontology-metadata-response.json",
      "destination": "./test/data/api/v2/ontologies/all-ontology-metadata-response.json"
    },
    ...
  ]
}

The example shown above will copy the file /v2/ontologies/all-ontology-metadata-response.json from the generated test data to the specified destination in this library's test data folder. In the unit tests, this file can then be used to mock request and response data.

When adding a new method to a v2 endpoint, only add the test data needed to test this method to facilitate the review process. Do not add v2 test data that is not used in the unit tests.

After integrating v2 test data, run npm run expand-jsonld-test-data.

Change Supported Version of DSP-API

DSP-JS-LIB is compatible with a release of DSP-API that is specified in vars.mk. To update the target release of DSP-API, the following steps have to be carried out:

  1. Update DSP-API version in vars.mk, e.g., change v13.0.0 to v13.1.0.
  2. Download test-data from DSP-API release with make get-test-data-from-release.
  3. Unpack generated test data and integrate it with make prepare-test-data.
  4. Run the unit tests with npm test from the project root.
  5. Check for differences in the generated test data with respect to the previous release of DSP-API. If there are changes in the test data that have no breaking effect, integrate them (add them to the git repo). Otherwise, DSP-JS has to be adapted to comply with the later version of DSP-JS. Also see section Integrating Generated Test Data from DSP-API.
  6. Run the e2e tests against the target release of DSP-API:
    • prepare the local publication of the library using npm run prepare-dev-publication
    • build the library and publish it locally with npm run yalc-publish
    • change to directory test-framework
    • add the locally build library using npm run yalc-add and run npm install
    • run npm run webdriver-update and then npm run e2e
  7. See if the tests pass on GitHub CI.

Unit Tests

Components have their own spec files defining unit tests. Since this library relies on DSP-API, static test data is generated from DSP-API and integrated automatically.

Actual calls to DSP-API in production are mocked with jasmine.Ajax. The data is read from the static test data files and passed to jasmine.Ajax, so the component being tested can react to it.

If a component A depends on a component B, then B has to be mocked during the test using a jasmine.Spy. The behavior of component B is simulated and a fake response is returned. Mocking components turned out to be quite complex for the OntologyCache. Therefore, a stand-alone testing component has been made for this mock called MockOntology that can be reused. It can also be used to generate static test data in software projects using this library.

Since MockOntology is complex, some global assertions are made to guarantee that the mock behaves like the actual component. These assertions are defined in MockOntologyAssertions.

Test Environment and E2E Tests

./test-framework provides a ready-to-use test environment for Angular developers. The E2E test for DSP-JS-LIB are run by the test environment. See the test framwork README for further instructions.