toBeFeatureCollection

[M-Scott-Lassiter]

Description

This is a building block matcher. FeatureCollections contain Feature objects and additional properties. We need a way to reliably test that they have been formatted appropriately.

This matcher tests that an object is a valid feature with any geometry type. Any non-conforming values should fail.

• It must have a "type" member equal to 'FeatureCollection'
• It must have a "features" member, but this may be an empty array ([]).

GeoJSON object with the type "FeatureCollection" is a FeatureCollection object. A FeatureCollection object has a member with the name "features". The value of "features" is a JSON array. Each element of the array is a Feature object as defined above. It is possible for this array to be empty.

~ https://datatracker.ietf.org/doc/html/rfc7946#section-3.3

The word "Collection" in "FeatureCollection" and "GeometryCollection" does not have any significance for the semantics of array members. The "features" and "geometries" members, respectively, of these objects are standard ordered JSON arrays, not unordered sets.

~ https://datatracker.ietf.org/doc/html/rfc7946#section-1.4

Foreign members ARE allowed (see https://datatracker.ietf.org/doc/html/rfc7946#section-6.1). None of these foreign members (to include "id") should get checked for validity of any type; they may contain anything that is valid JSON.

FeatureCollection objects are prohibited from having a "coordinates", "geometries", "geometry", or "properties" member.

Implementations MUST NOT change the semantics of GeoJSON members and types.

The GeoJSON "coordinates" and "geometries" members define Geometry objects. FeatureCollection and Feature objects, respectively, MUST NOT contain a "coordinates" or "geometries" member.

The GeoJSON "geometry" and "properties" members define a Feature object. FeatureCollection and Geometry objects, respectively, MUST NOT contain a "geometry" or "properties" member.

The GeoJSON "features" member defines a FeatureCollection object. Feature and Geometry objects, respectively, MUST NOT contain a "features" member.

~ https://datatracker.ietf.org/doc/html/rfc7946#section-7.1

See GeoJSON Spec: What does it mean to extend GeoJSON without using a foreign member? for further clarification.

Bounding boxes, if present, must validate (see isValidBoundingBox).

A GeoJSON object represents a Geometry, Feature, or collection of Features.

~ https://datatracker.ietf.org/doc/html/rfc7946#section-3

A GeoJSON object MAY have a member named "bbox" to include information on the coordinate range for its Geometries, Features, or FeatureCollections.

~ https://datatracker.ietf.org/doc/html/rfc7946#section-5

Valid GeoJSON Feature Examples

{
    "type": "FeatureCollection",
    "features": [{
        "type": "Feature",
        "geometry": {
            "type": "Point",
            "coordinates": [102.0, 0.5]
        },
        "properties": {
            "prop0": "value0"
        }
    }, {
        "type": "Feature",
        "geometry": {
            "type": "LineString",
            "coordinates": [
                [102.0, 0.0],
                [103.0, 1.0],
                [104.0, 0.0],
                [105.0, 1.0]
            ]
        },
        "properties": {
            "prop0": "value0",
            "prop1": 0.0
        }
    }, {
        "type": "Feature",
        "geometry": {
            "type": "Polygon",
            "coordinates": [
                [
                    [100.0, 0.0],
                    [101.0, 0.0],
                    [101.0, 1.0],
                    [100.0, 1.0],
                    [100.0, 0.0]
                ]
            ]
        },
        "properties": {
            "prop0": "value0",
            "prop1": {
                "this": "that"
            }
        }
    }]
}

An empty features

{
    "type": "FeatureCollection",
    "features": []
}

In all cases, the matcher should only get passed an object in its entirety, not the individual components.

Example Matcher Usage

const testFeatureCollectionCollection = {
    "type": "FeatureCollection",
    "features": [{
        "type": "Feature",
        "geometry": {
            "type": "Point",
            "coordinates": [102.0, 0.5]
        }
    },
    ...
    ]
}
const multiPoint = {
    type: "MultiPoint",
    coordinates: [
        [101.0, 0.0],
        [102.0, 1.0]
    ]
}

expect(testFeatureCollection).toBeFeature()

expect(multiPoint).not.toBeFeature()
expect(testFeatureCollection.features).not.toBeFeature('Polygon')

Passing Tests

This matcher should use core functions to test object validity.

Values in Range

• A FeatureCollection containing one feature with each of the seven geometry types
• A FeatureCollection containing all of the above features

Stress Test

• A FeatureCollection containing 10 features of each of the seven geometry types (70 total)

Features May Be an Empty Array

const testFeatureCollection = {
    type: 'FeatureCollection',
    features: []
}

May Have Optional Bounding Box

• Logical
  • 2D: [-10.0, -10.0, 10.0, 10.0]
  • 3D: [-10.0, -10.0, 0, 10.0, 10.0, 200]

const testFeatureCollection = {
    type: 'FeatureCollection',
    features: [{
        type: "MultiPoint",
        coordinates:[[0, 0], [1, 1, 100]]
    }],
    bbox: <input>
}

• Illogical

const testFeatureCollection = {
    type: 'FeatureCollection',
    features: [{
        type: "MultiPoint",
        coordinates:[[0, 0], [1, 1]]
    }],
    bbox: [-30.0, -30.0, -20.0, -20.0]
}

• Redundant

const testFeatureCollection = {
    type: 'FeatureCollection',
    features: [{
        type: "MultiPoint",
        coordinates:[[0, 0], [0, 0]]
    }],
    bbox: [0, 0, 0, 0]
}

ID is a Foreign Member, Can Be Anything

• null, undefined
• Boolean: true, false
• Strings: 'ABCD', 'Test 1', '1', '', '[[[180, 10.2, -125], [-180, 90, 35000]]], [{}]'
• Numbers: 0, 200, -200, Infinity, -Infinity, NaN
• Array: [], [1]
• Object: {}, {id: 1}

const testFeatureCollection = {
    type: 'FeatureCollection',
    id: <input>,
    features: []
}

Other Foreign Properties Allowed

• Single

const testFeatureCollection = {
    type: 'FeatureCollection',
    features: [],
    foreign: true
}

• Multiple

const testFeatureCollection = {
    type: 'FeatureCollection',
    features: [],
    id: '#1',
    foreign1: true,
    foreign2: 33
}

• Foreign property that would normally be a valid GeoJSON object

const testFeatureCollection = {
    type: 'FeatureCollection',
    features: [],
    foreignGeometry: multiPoint,
    Geometry: multiPoint // Note captitalized 'G'
}

Failing Tests

Feature Input Not an Object

Any of the following inputs to the matcher should fail:

• undefined
• null
• Booleans: true, false
• Numbers: 200, -200, Infinity, -Infinity, NaN
• Arrays: [25, 35, 45000], [ ]
• Strings: '', 'Random FeatureCollection'
• Stringified JSON:

  JSON.stringify({
    type: 'FeatureCollection',
    features: [{
        type: 'Feature',
        properties: {},
        geometry: {
            type: "MultiPoint",
            coordinates:[[0, 0], [1, 1, 100]]
        }
    }]
  })

Invalid Features

• A FeatureCollection containing one invalid feature with each of the seven geometry types
• A FeatureCollection containing all seven valid features plus one invalid

Type Value Incorrect

Input:

• Each of the values from "Feature Input Not an Object", plus
• 'Point', 'MultiPoint', 'LineString', 'MultiLineString' 'Polygon', 'MultiPolygon', and 'GeometryCollection', 'Feature', or
• 'FEATURECOLLECTION', 'featurecollection'

const testFeatureCollection = {
    type: <input>,
    features: []
}

Features Invalid

• Each of the values from "Feature Input Not an Object" except the empty array, both contained in an array and not contained in an array

const testFeatureCollection = {
    type: 'FeatureCollection',
    features: [<input>]
}

const testFeatureCollection = {
    type: 'FeatureCollection',
    features: <input>
}

Invalid Bounding Box

Input:

• null
• undefined
• []
• Missing Element: [-10.0, -10.0, 10.0]
• Out of Range Element: [-10.0, -10.0, 190.0, 10.0]
• South Greater than North: [-10.0, 10.0, 10.0, -10]
• Bad altitude: [-10.0, -10.0, 0, 10, 10.0, '200']

const testFeatureCollection = {
    type: 'FeatureCollection',
    features: [...],
    bbox: <input>
}

Contains Prohibited Properties

Coordinates

const testFeatureCollection = {
    type: 'FeatureCollection',
    features: [...],
    coordinates:[[0, 0], [1, 1]]
}

Geometries

const testFeatureCollection = {
    type: 'FeatureCollection',
    features: [...],
    geometries: [
        {
            type: 'Point',
            coordinates: [102.0, 0.5]
        }, {
            type: 'Point',
            coordinates: [122.0, -10.25]
        }
    ]
}

Geometry

const testFeatureCollection = {
    type: 'FeatureCollection',
    features: [...],
    geometry: {
        type: 'Point',
        coordinates: [102.0, 0.5]
    },
    id: 33
}

Properties

const testFeatureCollection = {
    type: 'FeatureCollection',
    features: [...],
    properties: {
        someProp: true
    }
}

Missing Required Properties

• No Type

const testFeatureCollection = {
    features: []
}

• No Features

const testFeatureCollection = {
    type: 'FeatureCollection'
}

[M-Scott-Lassiter]

🎉 This issue has been resolved in version 1.0.0-beta.16 🎉

The release is available on:

• npm package (@beta dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[M-Scott-Lassiter]

🎉 This issue has been resolved in version 1.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀