Bibliographic resource parsers lib

Welcome to Bibliographic resource parsers lib! This guide will walk you through setting up the development environment and getting started with contributing to the project.

Contributing

We follow the conventional commits specification for our PR titles. When creating a Pull Request, the title of the PR will be used as the commits will be squashed and merged in the main branch.

Therefore, it is mandatory to use conventional commit messages in the title of your PR. To enforce this, we use a GitHub action that validates the PR title conforms to the Conventional Commits conventions.

We use this standard to help us correctly version the project and generate changelogs automatically.

For more information about conventional commits, you can refer to Conventional Commits Specification.

Setting Up the Development Environment

Prerequisites

Before you begin, make sure you have the following installed:

• nvm
• Node.js - version is defined in .nvmrc file
• Git

Getting Started

git clone [email protected]:talis/bibliographic-resource-parsers-lib.git
cd bibliographic-resource-parsers-lib

You can run the following nvm command to install and use the required Node.js version:

nvm install && nvm use

Install Dependencies

npm install

Linting & Formatting

Code standards and formatting are enforced using ESLint and Prettier.

You can analyse your code for standards issues using:

npm run lint

You can reformat and apply automatic fixes by running:

npm run format

Build library

To build the library run:

npm run build

Running/Writing Tests

To run the tests, you can use the following command:

npm test

Parser Tests

Parser tests use HTML fixtures saved from real-world examples. These should be specified in the tests as URLs which will be mapped to fixtures and snapshots.

The general format of a parser test is as follows:

const urls = [
    'https://www.example.com',
];

test.each(urls)('should parse %s', async url => {
    const fixture = await loadFixture(__dirname, url);
    const resourceData = convertToResourceData(url, fixture);
    
    const result = yourParserUnderTest(resourceData);
    
    await expect(result).toMatchFileSnapshot(getSnapshotPath(__dirname, url));
});

If no fixture exists for a real-world example, the test will fail and prompt you to save the fixture using the command npm run save-fixture {url} {saveDirectory}. This will save the HTML from the URL to the specified directory. Running the test again will use the saved fixture.

The fixture should be run through the parser under test and compared against a snapshot of the expected output. If the snapshot does not exist, it will be created. If it mismatches the output, the test will fail and Vitest will prompt you to update the snapshot.