Skip to content

Latest commit

 

History

History
216 lines (151 loc) · 5.44 KB

CONTRIBUTING.md

File metadata and controls

216 lines (151 loc) · 5.44 KB
Raw

Install node dependencies

Installing the node depedencies only needs to be done once, and then again if they change.

npm install

How to run the tests

npm t

See How to write tests for further details.

How to visualize the tests

To visually inspect the results of the tests you can open the svg generated by the tests in a browser. The visualization writes the files into ./svg/<test-name>.html.

npm v

How to release

We use standard-release to manage the release process.

While we are still in beta phase need to manually specify release version to increment y as the default is to increment z when x === 0.

HUSKY_SKIP_HOOKS=1 npm run release -- --release-as 0.Y.0

This will automatically update the CHANGELOG.md file.

NOTE: Currently skipping husky hooks as they are failing standard-version changelog. See commitizen/cz-cli#631

Then push the code, as well as the newly created tag.

git push
git push --tags

How to publish to npm repository

Only the owner of the npm package can publish to the npm repository.

npm login
npm publish

How to obtain souce code

Follow the advice from Cloning a repository from GitHub

The repository is located at https://github.com/baerrach/gatsby-remark-plantuml.git

How to write tests

The tests are built with jest.

All test files are located in test/

  • test/index.spec.js tests the plugin usage
  • test/errors.spec.js tests error handling
  • test/max-width.spec.js tests the max-width feature
  • test/sequence.spec.js tests the sequence diagram capabilities
  • test/use-case.spec.js tests the use-case diagram capabilities

All snapshots are located in test/__snapshots__/<test-file-name>.js.snap and for each test block will contain a string for the snapshotted output. Reading the snapshot output can be a bit tricky, the most important bit is the value key which will contain the generated svg.

export[`test name`] = `
Object {
  "children": Array [
    Object {
      ...,
      "value": "<svg ...

Manually reading the svg contents is also tricky, it is better to visualize the tests and open the resulting file in the browser and check out the svg there.

General boiler plate for a test file

// <Description of tests purpose>

const testRemarkPlugin = require(`./test-remark-plugin`)

describe(`<Describe block for test group>`, () => {
  beforeEach(() => {
    jest.resetModules()
  })

  it(`<Single test name>`, async () => {
    const code = `
\`\`\`plantuml
@startuml
<Plant UML code to be tested>
@enduml
\`\`\`
`

    await testRemarkPlugin.testPlugin({
      code,
    })
  })
})

The testRemarkPlugin provides helpers to do all the heavy lifting in the tests.

The beforeEach block is necessary to reset the jest mocking before tests are run.

The code is tested via the .testPlugin call:

    await testRemarkPlugin.testPlugin({
      code,
    })

The testPlugin takes the provided code and makes use of snapshot testing to compare the generated svg with the snapshot version. It is important that you visualize your test to ensure it is correct before commiting the test snapshot.

Fill in the <blanks> as described below.

Description of tests purpose

Include the purpose of the test as a comment at the top of the file.

If this is from the https://plantuml.com/ examples then include a link.

Describe block for test group

Give a meaningful grouping of the contained tests.

If this is from the https://plantuml.com/ examples then name it after the heading it is contained within.

Single test name

Give a meaningful name to your test.

If this is from the https://plantuml.com/ examples then name it after the example. Multiple examples with the same name will include a counter suffix.

Plant UML code to be tested

Paste, or create yourself, the plantuml code to be tested.

If this is from the https://plantuml.com/ examples then copy the code from the example.

Testing Errors

testRemarkPlugin.testPlugin accepts another property reporter which contains the expected Gatsby reporter outputs.

Each reporter is passed an ordered array of expected values that the reporter should have received.

In most cases this will be a single string, the value that should have been written to the reporter.

reporter: {
  info: [
    'First message sent to reporter',
    'Second message sent to reporter',
    ...
  ],

If an Error is also required then an array is used to contain both the message and the error.

reporter: {
  error: [
    ['An error occured', new PlantUmlError('Cause of Error')],
    'More error messages can come afterwards',
  ],

When the reporter should not have any output do not specify that key. Only reporters that are expected to receive a report need to be provided.

Example shape of reporter

reporter: {
  info: [],
  warn: [],
  error: [],
  panic: [],
  panicOnBuild: [],
}

How to view the markdown files locally

Use grip