• Purpose
• Getting Started
  • Install as a Dependency
  • Configure Jest
  • Configure Typescript
• Matchers
  • Coordiantes
  • Bounding Boxes
  • Geometries
  • Features
  • Feature Collections
  • Functional
• Advanced Configuration
  • Load Matchers by Category
  • Load Specific Matchers
  • Import the Core Engine
• Support Policy
  • Minimum Supported Jest Version
  • Node and Operating System
• License and Development
• Contact

Purpose

Jest-GeoJSON extends the Jest unit testing framework with a comprehensive set of matchers tailored to checking GeoJSON object validity and other geodesy attributes. For example:

const testPoint = {
    type: 'Point',
    coordinates: [25, 10.2]
}

test('Object is valid GeoJSON Point Geometry', () => {
    expect(testPoint).toBePointGeometry()
})

This library DOES NOT create or manipulate GeoJSON. Other tools have done that (and better), such as the venerable Turf.js.

This project complements, not competes with, those tools.

Getting Started

Install as a Dependency

After installing Jest, run:

npm install --save-dev jest-geojson

Configure Jest

Jest will run custom scripts after its environment loads. You can take advantage of that to load all Jest-GeoJSON matchers automatically.

To do so, either create a jest.config.js file:

module.exports = {
    setupFilesAfterEnv: ['jest-geojson/setup/all']
}

or add a key to your package.json:

{
    "name": "myPackageName",
    ...
    "jest": {
        "setupFilesAfterEnv": ["jest-geojson/setup/all"]
    }
}

Configure Typescript

If your editor does not recognize the custom Jest-GeoJSON matchers, add a global.d.ts file to your project with:

import 'jest-geojson'

Then add a files key in your tsconfig.json:

{
  "compilerOptions": {
    ...
  },
  ...
  "files": ["global.d.ts"]
}

Matchers

Jest-GeoJSON organizes matchers by categories. Most correspond to the expected input type passed to expect(). For example, the Coordinates matchers expect a coordinate array, and geometry matchers expect a GeoJSON geometry object.

Functional matchers assess more generic attributes and qualities and many accept multiple input types.

Coordiantes

• isValid2DCoordinate
• isValid3DCoordinate
• isValidCoordinate

Bounding Boxes

• isValid2DBoundingBox
• isValid3DBoundingBox
• isValidBoundingBox

Geometries

• toBeAnyGeometry
• toBeGeometryCollection
• toBeLineStringGeometry
• toBeMultiLineStringGeometry
• toBeMultiPointGeometry
• toBeMultiPolygonGeometry
• toBeMultiPolygonWithHole
• toBePointGeometry
• toBePolygonGeometry
• toBePolygonWithHole
• toHaveGeometryCount
• toHaveMaxGeometryCount
• toHaveMinGeometryCount

Features

• toBeFeature
• toHaveID
• toHaveNumericID
• toHaveStringID

Future

• [ ] toHaveProperties (array of [property, optional values])

Feature Collections

• toBeFeatureCollection

Future

• [ ] toContainFeatureTypes (array of feature type strings, optional min count, optional max count)
• [ ] toContainIDs ([optional unordered array of IDs])
• [ ] toContainStringIDs
• [ ] toContainNumericIDs
• [ ] toContainUniqueIDs
• [ ] toContainAnyIDs
• [ ] toContainOnlyIDs ([unordered array of IDs])

Functional

• toBeValidGeoJSON

Future

• [ ] toHave2DBoundingBox
• [ ] toHave3DBoundingBox
• [ ] toHaveBoundingBox
• [ ] toCrossAntimeridian
• [ ] toIncludePole (Optional 'North' or 'South')
• [ ] isInHemisphere('North', 'South', 'East', 'West')
• [ ] toHaveMinPointCount
• [ ] toHaveMaxPointCount
• [ ] toHavePointCount (equal/min, optional max)
• [ ] toHaveMaxPrecision (num decimal places)
• [ ] toHaveMinPrecision (num decimal places)
• [ ] toHavePrecision (equal to/min decimal places, optional max decimal places)
• [ ] toIncludeGeometryTypes (optional array of [Geometry type strings, optional min count, optional max count])
• [ ] toIncludeForeignMembers (optional array of [members, optional values])
• [ ] toIncludeAnyCoordinates ([unordered array of points])
• [ ] toIncludeAllCoordinates ([unordered array of points])
• [ ] toIncludeOnlyCoordinates
• [ ] toIncludeOrderedCoordinates (array of [ordered points])
• [ ] toContain (array of geometry: [single or multi point/line/polygon whose boundaries are all within argument polygon/multipolygon])
• [ ] isCounterClockwiseWound
• [ ] isClockwiseWound
• [ ] isKinked
• [ ] toBeContainedWithinBBox
• [ ] toBeContainedWithinPolygon

Advanced Configuration

Load Matchers by Category

You can load matcher subsets if you only need a limited set. Available scipts are:

• jest-geojson/setup/all
• jest-geojson/setup/boundingBoxes
• jest-geojson/setup/coordinates
• jest-geojson/setup/featureCollections
• jest-geojson/setup/features
• jest-geojson/setup/geometries

For example:

module.exports = {
    setupFilesAfterEnv: ['jest-geojson/setup/coordinates']
}

To load more than one matcher set, pass a comma separated list to the setupFilesAfterEnv array:

module.exports = {
    setupFilesAfterEnv: [
        'jest-geojson/setup/featureCollections',
        'jest-geojson/setup/geometries',
        'jest-geojson/setup/features'
    ]
}

Load Specific Matchers

To load only specific matchers, create a new script and import them either one by one or by group. The matcher object contains each matcher grouped by category.

// ./my-custom-load-script.js

const matchers = require('jest-geojson')

expect.extend({ matchers.coordinates.isValidCoordinate }) // Loads single matcher
expect.extend({ matchers.boundingBoxes.isValidBoundingBox }) // Loads single matcher
expect.extend(matchers.geometries) // Loads all matchers in the geometries category

For another example, see the setup script.

Import the Core Engine

The core object contains the functions grouped by category. You can then use these functions elsewhere in your code, or even port Jest-GeoJSON into another testing framework. To import the functions that drive the test matchers:

const core = require('jest-geojson/core')

Support Policy

Minimum Supported Jest Version

This project requires Jest v24.0.0 or newer.

Node and Operating System

The test suite has successfully run on all combinations of:

This project supports Long-Term Support, Current, and Maintenance versions of node. Once a version reaches end of life, the CI scripts will no longer support them. Odd Node versions will only receive support while in a current status.

Other Node versions and operating systems might support the library, but the tests have not verified other combinations.

License and Development

Jest-GeoJSON and all other files in this repository are distributed as free and open-source software under the MIT License, © 2022.

Both contributions and bug reports welcome.

Leave a :star2: if you find this project useful!

Contact

Maintained by M. Scott Lassiter.