M-Scott-Lassiter
---
---
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-geojsonConfigure 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
Bounding Boxes
Geometries
- toBeAnyGeometry
- toBeGeometryCollection
- toBeLineStringGeometry
- toBeMultiLineStringGeometry
- toBeMultiPointGeometry
- toBeMultiPolygonGeometry
- toBeMultiPolygonWithHole
- toBePointGeometry
- toBePolygonGeometry
- toBePolygonWithHole
- toHaveGeometryCount
- toHaveMaxGeometryCount
- toHaveMinGeometryCount
Features
Future
- [ ] toHaveProperties (array of [property, optional values])
Feature Collections
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
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/alljest-geojson/setup/boundingBoxesjest-geojson/setup/coordinatesjest-geojson/setup/featureCollectionsjest-geojson/setup/featuresjest-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 categoryFor 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.
