MapGrab

https://mapgrab.github.io/docs/
Admin
MapGrab is a tool that enables the writing of automated map tests based on the MapLibre GL JS and...
Tokens:11,026
Snippets:136
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Mapgrab Cypress with npm

Source: https://mapgrab.github.io/docs/getting-started/stage-two/cypress

Install the Mapgrab Cypress dependency using npm.

```bash
 npm i --save @mapgrab/cypress  
```

--------------------------------

### Install Mapgrab Cypress with pnpm

Source: https://mapgrab.github.io/docs/getting-started/stage-two/cypress

Install the Mapgrab Cypress dependency using pnpm.

```bash
 pnpm add @mapgrab/cypress  
```

--------------------------------

### Install Playwright Dependency with Yarn

Source: https://mapgrab.github.io/docs/getting-started/stage-two/playwright

Install the MapGrab Playwright dependency using Yarn.

```bash
yarn add @mapgrab/playwright
```

--------------------------------

### Install Map Interface with npm

Source: https://mapgrab.github.io/docs/getting-started/stage-one

Use this command to install the @mapgrab/map-interface package using npm.

```bash
npm i --save @mapgrab/map-interface  

```

--------------------------------

### Install Mapgrab Cypress with yarn

Source: https://mapgrab.github.io/docs/getting-started/stage-two/cypress

Install the Mapgrab Cypress dependency using yarn.

```bash
 yarn add @mapgrab/cypress  
```

--------------------------------

### Install Map Interface with pnpm

Source: https://mapgrab.github.io/docs/getting-started/stage-one

Use this command to install the @mapgrab/map-interface package using pnpm.

```bash
pnpm add @mapgrab/map-interface  

```

--------------------------------

### Install Map Interface with Yarn

Source: https://mapgrab.github.io/docs/getting-started/stage-one

Use this command to install the @mapgrab/map-interface package using Yarn.

```bash
yarn add @mapgrab/map-interface  

```

--------------------------------

### Setup Mapgrab Cypress Commands

Source: https://mapgrab.github.io/docs/getting-started/stage-two/cypress

Add the setupCommands import and call to your e2e.ts support file to integrate Mapgrab commands.

```typescript
//support/e2e.ts  
  
import { setupCommands } from '@mapgrab/cypress';  
  
import './commands';  
  
setupCommands();  
```

--------------------------------

### Install Playwright Dependency with pnpm

Source: https://mapgrab.github.io/docs/getting-started/stage-two/playwright

Install the MapGrab Playwright dependency using pnpm.

```bash
pnpm add @mapgrab/playwright
```

--------------------------------

### Standard Map Interface Installation

Source: https://mapgrab.github.io/docs/getting-started/stage-one

This code snippet shows the standard way to install the MapGrab interface. It includes direct imports for the Maplibre-gl Map and the installMapGrab function. Ensure the Maplibre-gl Map instance is correctly initialized.

```typescript
  import { Map } from 'maplibre-gl';  
  import { installMapGrab } from '@mapgrab/map-interface';  
  
  function initMap(): void {  
    const map = new Map({  
      container: 'map',  
      style: 'https://demotiles.maplibre.org/style.json',  
      center: [0, 0],  
      zoom: 1,  
      attributionControl: false,  
      clickTolerance: 5,  
    });  
  
    // process.env.RUN_ONLY_IN_TEST_ENV is given as an example  
    if (process.env.RUN_ONLY_IN_TEST_ENV) {  
      installMapGrab(map, 'mainMap');  
    }  
  }  


```

--------------------------------

### Install Playwright Dependency with npm

Source: https://mapgrab.github.io/docs/getting-started/stage-two/playwright

Install the MapGrab Playwright dependency using npm.

```bash
npm i --save @mapgrab/playwright
```

--------------------------------

### Get First Matching Element (Cypress)

Source: https://mapgrab.github.io/docs/API/locator

In Cypress, use `.first()` to select the first element matching the selector. This is typically chained after a `cy.mapLocator()` call.

```typescript
it('foo test', () => {
  cy.mapLocator('layer[id=cities]')
    .first<MapLocator>()
    .then((locator) => locator.click());
});
```

--------------------------------

### Get Map Instance (Cypress)

Source: https://mapgrab.github.io/docs/API/controller

Retrieves the underlying Mapbox GL JS or Maplibre GL JS instance using Cypress. This allows for direct execution of map methods via `evaluate`.

```javascript
it('foo test', () => {
  cy.mapController('mainMap').then((controller) => {
    return mapController('mainMap').getMapInstance().then((map) => {
      map.evaluate((map) => map.jumpTo(...));
    });
  });
});

```

--------------------------------

### Get Nth Matching Element (Cypress)

Source: https://mapgrab.github.io/docs/API/locator

In Cypress, use `.eq(index)` to get the Nth element, where the index is zero-based. This allows precise selection within a group of elements.

```typescript
it('foo test', () => {
  cy.mapLocator('layer[id=cities]')
    .eq<MapLocator>(2)
    .then((locator) => locator.click());
});
```

--------------------------------

### Get First Matching Element (Playwright)

Source: https://mapgrab.github.io/docs/API/locator

Use the `.first()` method to get a locator for the first element that matches the selector. This is useful when you only need to interact with the initial element found.

```typescript
test("foo test", async ({ mapLocator }) => {
  const locator = mapLocator('layer[id=cities]').first();

  await locator.click();
  ...
});
```

--------------------------------

### Get Bounding Box (Cypress)

Source: https://mapgrab.github.io/docs/API/locator

In Cypress, `.boundingBox()` retrieves the bounding box of a map element. This data is useful for positioning or fitting the map.

```typescript
it('foo test', () => {
  cy.mapLocator('layer[id=cities]')
    .first()
    .then((locator) => locator.boundingBox());
});
```

--------------------------------

### Get Bounding Box (Playwright)

Source: https://mapgrab.github.io/docs/API/locator

The `.boundingBox()` method returns the bounding box coordinates of a map element. This information can be used for map fitting or other spatial calculations.

```typescript
test("foo test", async ({ mapLocator, mapController }) => {
  const controller = mapController('mainMap');
  const city = mapLocator('layer[id=cities]').first();
  const bbox = await city.boundingBox();

  await controller.fitMapToBoundingBox(bbox, { padding: 5 });
  ...
});
```

--------------------------------

### Count Matching Elements (Playwright)

Source: https://mapgrab.github.io/docs/API/locator

Use `.count()` to get the total number of elements that match the locator. This is useful for assertions or conditional logic.

```typescript
test("foo test", async ({ mapLocator }) => {
  const citiesCount = await mapLocator('layer[id=cities]').count();

  expect(citiesCount).toBe(22);
  ...
});
```

--------------------------------

### Get Nth Matching Element (Playwright)

Source: https://mapgrab.github.io/docs/API/locator

Select the Nth element from the matching set using `.nth(index)`. Remember that the index is zero-based.

```typescript
test("foo test", async ({ mapLocator }) => {
  const locator = mapLocator('layer[id=cities]').nth(2);

  await locator.click();
  ...
});
```

--------------------------------

### Get Map Instance (Playwright)

Source: https://mapgrab.github.io/docs/API/controller

Retrieves the underlying Mapbox GL JS or Maplibre GL JS instance. Use this to execute custom JavaScript directly on the map object.

```typescript
test("foo test", async ({ mapController, mapLocator, page }) => {
  const map = await mapController('mainMap').getMapInstance();
  
  await map.evaluate((map) => map.jumpTo(...));
  ...
});

```

--------------------------------

### Get Last Matching Element (Cypress)

Source: https://mapgrab.github.io/docs/API/locator

Use `.last()` in Cypress to target the last element that matches the specified selector. This is often used when dealing with ordered lists or sequences.

```typescript
it('foo test', () => {
  cy.mapLocator('layer[id=cities]')
    .last<MapLocator>()
    .then((locator) => locator.click());
});
```

--------------------------------

### Get Last Matching Element (Playwright)

Source: https://mapgrab.github.io/docs/API/locator

Retrieve a locator for the last element matching the selector using the `.last()` method. This is useful for targeting the final element in a set of results.

```typescript
test("foo test", async ({ mapLocator }) => {
  const locator = mapLocator('layer[id=cities]').last();

  await locator.click();
  ...
});
```

--------------------------------

### Fit Map to Bounding Box by Screen Point (Cypress)

Source: https://mapgrab.github.io/docs/API/controller

Fits the map to a bounding box defined by screen x/y coordinates using Cypress. Requires a bounding box object and optional padding.

```javascript
it('foo test', () => {
  cy.mapController('mainMap').then((controller) => {
    const bbox = new MapRect(20, 20, 400, 400)

    controller.fitMapToBoundingBox(bbox, { padding: 5 });
  });
});
```

--------------------------------

### Project Lng/Lat to Screen Point (Cypress)

Source: https://mapgrab.github.io/docs/API/controller

Converts geographic coordinates (longitude, latitude) to screen coordinates (x, y) using Cypress. Useful for interacting with specific map locations.

```javascript
it('foo test', () => {
  cy.mapController('mainMap').then((controller) => {
    controller.projectLngLatToScreenPoint({ lng: 12, lat: 11 }).then(({ x, y }) => {
      cy.click(x, y);
    });
  });
});
```

--------------------------------

### Fit Map to Bounds by Lng/Lat (Cypress)

Source: https://mapgrab.github.io/docs/API/controller

Fits the map to specified bounds defined by longitude and latitude using Cypress. Includes an optional duration for the transition.

```javascript
it('foo test', () => {
  cy.mapController('mainMap').then((controller) => {
    controller.fitMapToBounds([11, 11, 14, 14], { duration: 11 });
  });
});
```

--------------------------------

### fitMapToBoundingBox

Source: https://mapgrab.github.io/docs/API/controller

Fits the map to a specified bounding box defined by screen x/y coordinates. Supports Playwright and Cypress.

```APIDOC
## fitMapToBoundingBox

### Description
Fits the map to a specified bounding box defined by screen x/y coordinates.

### Usage
- playwright
- cypress

### Parameters
#### Request Body
- **boundingBox** (object) - Required - An object representing the bounding box, typically obtained from `locator.boundingBox()` or a `MapRect` object.
- **options** (object) - Optional - An object for additional options, such as `padding`.
  - **padding** (number) - Optional - Padding around the bounding box.

### Example (Playwright)
```javascript
test("foo test", async ({ mapController, mapLocator }) => {
  const controller = mapController('mainMap');
  const city = mapLocator('layer[id=cities]').first();
  const bbox = await locator.boundingBox();

  await controller.fitMapToBoundingBox(bbox, { padding: 5 });
  // ...
});
```

### Example (Cypress)
```javascript
it('foo test', () => {
  cy.mapController('mainMap').then((controller) => {
    const bbox = new MapRect(20, 20, 400, 400);

    controller.fitMapToBoundingBox(bbox, { padding: 5 });
  });
});
```
```

--------------------------------

### First Playwright Test with Fixtures

Source: https://mapgrab.github.io/docs/getting-started/stage-two/playwright

Write your first Playwright test using fixtures to interact with the map, set its view, and assert element visibility.

```typescript
//tests/my-test.spec.ts
import { test, expect } from '../support';

test('Country should display on map', async ({ page, mapLocator, mapController }) => {
  await page.goto('/');
  await mapController('mainMap').setView({ zoom: 2, center: [22, 42] });
  const country = mapLocator('map[id=mainMap] layer[id=countries-fill] filter["all", ["==", ["get", "fid"], 74]]');

  await expect(country).toBeVisibleOnMap();
});

```

--------------------------------

### first()

Source: https://mapgrab.github.io/docs/API/locator

Returns a locator for the first matching element found by the selector.

```APIDOC
## first()

### Description
Returns a locator to the first matching element.

### Method
Chained method after a mapLocator call.

### Parameters
None

### Request Example
```javascript
// Playwright
const locator = mapLocator('layer[id=cities]').first();
await locator.click();
```

```javascript
// Cypress
cy.mapLocator('layer[id=cities]').first<MapLocator>().then((locator) => locator.click());
```

### Response
Returns a locator object for the first matching element.
```

--------------------------------

### boundingBox()

Source: https://mapgrab.github.io/docs/API/locator

Returns the bounding box of the element represented by the locator.

```APIDOC
## boundingBox()

### Description
Returns the bounding box of the element on the map.

### Method
Chained method after a locator object.

### Parameters
None

### Request Example
```javascript
// Playwright
const city = mapLocator('layer[id=cities]').first();
const bbox = await city.boundingBox();
```

```javascript
// Cypress
cy.mapLocator('layer[id=cities]').first().then((locator) => locator.boundingBox());
```

### Response
* **bbox** (object) - An object containing the bounding box details (e.g., x, y, width, height).
```

--------------------------------

### Support File for Playwright Fixtures

Source: https://mapgrab.github.io/docs/getting-started/stage-two/playwright

Configure support files to merge Playwright and MapGrab tests and expectations when using fixtures.

```typescript
// support/index.ts
import { test as playwrightTest, mergeTests, expect as playwrightExpect, mergeExpects } from '@playwright/test';
import { test as mapGrabTest, expect as mapGrabExpect } from '@mapgrab/playwright';

export const test = mergeTests(playwrightTest, mapGrabTest);
export const expect = mergeExpects(playwrightExpect, mapGrabExpect);

```

--------------------------------

### screenshot(options?)

Source: https://mapgrab.github.io/docs/API/locator

Takes a screenshot of the element represented by the locator. (Playwright only)

```APIDOC
## screenshot(options?)

### Description
Returns the screenshot for element on map.

### Method
Chained method after a locator object. (Playwright only)

### Parameters
* **options** (object) - Optional - Configuration options for the screenshot.
  * **padding** (number) - Optional - Padding around the element.
  * **backgroundColor** (string) - Optional - Background color for the screenshot.

### Request Example
```javascript
// Playwright
const snap = await mapLocator('layer[id=cities]').first().screenshot({ padding: 11, backgroundColor: 'red' });
await expect(snap).toMatchSnapshot('cities.png');
```

### Response
* **snap** (string) - The screenshot data.
```

--------------------------------

### fitMap()

Source: https://mapgrab.github.io/docs/API/locator

Fits the map to the bounding box of the locator element.

```APIDOC
## fitMap()

### Description
Fit map to locator element bounding box.

### Method
Chained method after a locator object.

### Parameters
None

### Request Example
```javascript
// Playwright
await mapLocator('layer[id=cities]').first().fitMap();
```

```javascript
// Cypress
cy.mapLocator('layer[id=cities]').first().then((locator) => locator.fitMap());
```

### Response
None. This method performs an action on the map.
```

--------------------------------

### fitMapToBounds

Source: https://mapgrab.github.io/docs/API/controller

Fits the map to specified bounds defined by longitude and latitude. Supports Playwright and Cypress.

```APIDOC
## fitMapToBounds

### Description
Fits the map to specified bounds defined by longitude and latitude.

### Usage
- playwright
- cypress

### Parameters
#### Request Body
- **bounds** (Array<number>) - Required - An array representing the bounds [southWestLng, southWestLat, northEastLng, northEastLat].
- **options** (object) - Optional - An object for additional options, such as `duration`.
  - **duration** (number) - Optional - The duration of the fit animation.

### Example (Playwright)
```javascript
test("foo test", async ({ mapController }) => {
  await mapController('mainMap').fitMapToBounds([11, 11, 14, 14], { duration: 11 });
  // ...
});
```

### Example (Cypress)
```javascript
it('foo test', () => {
  cy.mapController('mainMap').then((controller) => {
    controller.fitMapToBounds([11, 11, 14, 14], { duration: 11 });
  });
});
```
```

--------------------------------

### dblclick()

Source: https://mapgrab.github.io/docs/API/locator

Performs a double-click action on the element represented by the locator.

```APIDOC
## dblclick()

### Description
Double click an element on map.

### Method
Chained method after a locator object.

### Parameters
None

### Request Example
```javascript
// Playwright
await mapLocator('layer[id=cities]').first().dblclick();
```

```javascript
// Cypress
cy.mapLocator('layer[id=cities]').first().then((locator) => locator.dblclick());
```

### Response
None. This method performs a double-click action.
```

--------------------------------

### Write First Cypress Test for Map

Source: https://mapgrab.github.io/docs/getting-started/stage-two/cypress

Write a basic Cypress test to verify that a city layer is visible on the map.

```typescript
describe('Map', { testIsolation: false }, () => {  
  it('should display city on map', () => {  
    cy.mapLocator('layer[id=cities]').first().should('be.visibleOnMap');  
  });  
});  
```

--------------------------------

### Wait for Map to Load (Cypress)

Source: https://mapgrab.github.io/docs/API/controller

Waits until the map has finished loading using Cypress. This is essential for synchronizing test actions with the map's ready state.

```javascript
it('foo test', () => {
  cy.mapController('mainMap').then((controller) => {
    return controller.waitToMapLoaded();
  });
});

```

--------------------------------

### Count Matching Elements (Cypress)

Source: https://mapgrab.github.io/docs/API/locator

In Cypress, `.then((locator) => locator.count())` followed by `.should('have.eq', count)` can be used to assert the number of matching elements.

```typescript
it('foo test', () => {
  cy.mapLocator('layer[id=cities]')
    .then((locator) => locator.count())
    .should('have.eq', 22);
});
```

--------------------------------

### click()

Source: https://mapgrab.github.io/docs/API/locator

Performs a click action on the element represented by the locator.

```APIDOC
## click()

### Description
Click an element on map.

### Method
Chained method after a locator object.

### Parameters
None

### Request Example
```javascript
// Playwright
await mapLocator('layer[id=cities]').first().click();
```

```javascript
// Cypress
cy.mapLocator('layer[id=cities]').first().then((locator) => locator.click());
```

### Response
None. This method performs a click action.
```

--------------------------------

### count()

Source: https://mapgrab.github.io/docs/API/locator

Returns the number of elements matching the locator.

```APIDOC
## count()

### Description
Returns the number of elements matching the locator.

### Method
Chained method after a mapLocator call.

### Parameters
None

### Request Example
```javascript
// Playwright
const citiesCount = await mapLocator('layer[id=cities]').count();
expect(citiesCount).toBe(22);
```

```javascript
// Cypress
cy.mapLocator('layer[id=cities']).then((locator) => locator.count()).should('have.eq', 22);
```

### Response
* **citiesCount** (number) - The total number of elements matching the locator.
```

--------------------------------

### Fit Map to Element Bounds (Cypress)

Source: https://mapgrab.github.io/docs/API/locator

In Cypress, `.fitMap()` is used to center the map on the bounding box of the target element. This ensures the element is within the visible map area.

```typescript
it('foo test', () => {
  cy.mapLocator('layer[id=cities]')
    .first()
    .then((locator) => locator.fitMap());
});
```

--------------------------------

### Enable MapGrab Inspector (Cypress)

Source: https://mapgrab.github.io/docs/API/controller

Enables the MapGrab inspector for a specific map instance using Cypress.

```javascript
it('foo test', () => {
  cy.mapController('mainMap').then((controller) => {
    controller.enableInspector();
  });
});
```

--------------------------------

### projectLngLatToScreenPoint

Source: https://mapgrab.github.io/docs/API/controller

Converts geographic coordinates (longitude/latitude) to screen coordinates (x/y). Supports Playwright and Cypress.

```APIDOC
## projectLngLatToScreenPoint

### Description
Converts geographic coordinates to screen coordinates.

### Usage
- playwright
- cypress

### Parameters
#### Request Body
- **coordinates** (object) - Required - An object containing `lng` (longitude) and `lat` (latitude).
  - **lng** (number) - Required - The longitude.
  - **lat** (number) - Required - The latitude.

### Response
#### Success Response
- **x** (number) - The screen x-coordinate.
- **y** (number) - The screen y-coordinate.

### Example (Playwright)
```javascript
test("foo test", async ({ mapController, mapLocator, page }) => {
  const controller = mapController('mainMap');

  const { x, y } = await controller.projectLngLatToScreenPoint({ lng: 12, lat: 11 });

  await page.mouse.click(x, y);
  // ...
});
```

### Example (Cypress)
```javascript
it('foo test', () => {
  cy.mapController('mainMap').then((controller) => {
    controller.projectLngLatToScreenPoint({ lng: 12, lat: 11 }).then(({ x, y }) => {
      cy.click(x, y);
    });
  });
});
```
```

--------------------------------

### Fit Map to Bounding Box by Screen Point (Playwright)

Source: https://mapgrab.github.io/docs/API/controller

Fits the map to a bounding box defined by screen x/y coordinates using Playwright. Requires a bounding box object and optional padding.

```typescript
test("foo test", async ({ mapController, mapLocator }) => {
  const controller = mapController('mainMap');
  const city = mapLocator('layer[id=cities]').first();
  const bbox = await locator.boundingBox();

  await controller.fitMapToBoundingBox(bbox, { padding: 5 });
  ...
});
```

--------------------------------

### Set Map View by Screen Point (Cypress)

Source: https://mapgrab.github.io/docs/API/controller

Sets the map view to a specific center point defined by screen x/y coordinates using Cypress.

```javascript
it('foo test', () => {
  cy.mapController('mainMap').then((controller) => {
    controller.setViewAbsolute({ center: [240, 321] });
  });
});
```

--------------------------------

### First Playwright Test Without Fixtures

Source: https://mapgrab.github.io/docs/getting-started/stage-two/playwright

Write your first Playwright test without fixtures, manually initializing MapLocator and MapController to interact with the map.

```typescript
//tests/my-test.spec.ts
import { test, expect } from '@playwright/test';
import { MapLocator, MapController } from '@mapgrab/playwright';

test('Country should display on map', async ({ page }) => {
    await page.goto('/');
    const mapController = new MapController(page, 'mainMap');
    const country = new MapLocator(
      page,
      'map[id=mainMap] layer[id=countries-fill] filter["all", ["==", ["get", "fid"], 74]]'
    );

    await mapController.setView({ zoom: 2, center: [22, 42] });

    await expect(country).toBeVisibleOnMap();
});

```

--------------------------------

### Fit Map to Bounds by Lng/Lat (Playwright)

Source: https://mapgrab.github.io/docs/API/controller

Fits the map to specified bounds defined by longitude and latitude using Playwright. Includes an optional duration for the transition.

```typescript
test("foo test", async ({ mapController }) => {
  await mapController('mainMap').fitMapToBounds([11, 11, 14, 14], { duration: 11 });
  ...
});
```

--------------------------------

### Revert Layer Expose State (Cypress)

Source: https://mapgrab.github.io/docs/API/controller

Restores the previous state of layer visibility after using exposeLayers, using Cypress. Requires the state returned from exposeLayers.

```javascript
it('foo test', () => {
  cy.mapController('mainMap').then((controller) => {
    controller.exposeLayers(['countries-label'], ['countries-fill']).then((state) => {
      controller.revertExposeLayers(state);
    });
  });
});
```

--------------------------------

### setViewAbsolute

Source: https://mapgrab.github.io/docs/API/controller

Sets the map view based on screen x/y coordinates. Available for Playwright and Cypress.

```APIDOC
## setViewAbsolute

### Description
Sets the map view based on screen x/y coordinates.

### Usage
- playwright
- cypress

### Parameters
#### Request Body
- **center** (Array<number>) - Required - An array containing the screen x and y coordinates for the center of the view.

### Example (Playwright)
```javascript
test("foo test", async ({ mapController }) => {
  await mapController('mainMap').setViewAbsolute({ center: [240, 321] });
  // ...
});
```

### Example (Cypress)
```javascript
it('foo test', () => {
  cy.mapController('mainMap').then((controller) => {
    controller.setViewAbsolute({ center: [240, 321] });
  });
});
```
```

--------------------------------

### waitToMapLoaded

Source: https://mapgrab.github.io/docs/API/controller

Waits until the map has finished loading its initial data and tiles. This is crucial for ensuring that subsequent interactions or assertions are performed on a fully rendered map.

```APIDOC
## waitToMapLoaded

### Description
Waits until the map is loaded.

### Method
Not applicable (SDK method)

### Endpoint
Not applicable (SDK method)

### Parameters
None

### Request Example
```javascript
controller.waitToMapLoaded()
```

### Response
#### Success Response
None

#### Response Example
None
```

--------------------------------

### Project Lng/Lat to Screen Point (Playwright)

Source: https://mapgrab.github.io/docs/API/controller

Converts geographic coordinates (longitude, latitude) to screen coordinates (x, y) using Playwright. Useful for interacting with specific map locations.

```typescript
test("foo test", async ({ mapController, mapLocator, page }) => {
  const controller = mapController('mainMap');
    
  const { x, y } = await controller.projectLngLatToScreenPoint({ lng: 12, lat: 11 });
  
  await page.mouse.click(x, y);
  ...
});
```

--------------------------------

### Lazy Load Map Interface

Source: https://mapgrab.github.io/docs/getting-started/stage-one

This code snippet demonstrates how to lazily load the MapGrab interface. It's recommended for optimizing application size. Ensure the Maplibre-gl Map instance is correctly initialized.

```typescript
  import { Map } from 'maplibre-gl';  
    
  function initMap(): void {  
    const map = new Map({  
      container: 'map',  
      style: 'https://demotiles.maplibre.org/style.json',  
      center: [0, 0],  
      zoom: 1,  
      attributionControl: false,  
      clickTolerance: 5,  
    });  
  
    // process.env.RUN_ONLY_IN_TEST_ENV is given as an example  
    if (process.env.RUN_ONLY_IN_TEST_ENV) {  
      import('@mapgrab/map-interface').then(({ installMapGrab }) => {  
        installMapGrab(map, 'mainMap');  
      });  
    }  
  }  


```

--------------------------------

### setView

Source: https://mapgrab.github.io/docs/API/controller

Sets the map view based on longitude and latitude coordinates. Supports both Playwright and Cypress.

```APIDOC
## setView

### Description
Sets the map view based on longitude and latitude coordinates.

### Usage
- playwright
- cypress

### Parameters
#### Request Body
- **center** (Array<number>) - Required - An array containing the longitude and latitude for the center of the view.

### Example (Playwright)
```javascript
test("foo test", async ({ mapController }) => {
  await mapController('mainMap').setView({ center: [11, 12] });
  // ...
});
```

### Example (Cypress)
```javascript
it('foo test', () => {
  cy.mapController('mainMap').then((controller) => {
    controller.setView({ center: [11, 12] });
  });
});
```
```

--------------------------------

### nth(index)

Source: https://mapgrab.github.io/docs/API/locator

Returns a locator for the nth matching element found by the selector.

```APIDOC
## nth(index)

### Description
Returns a locator to the nth matching element.

### Method
Chained method after a mapLocator call.

### Parameters
* **index** (number) - Required - The zero-based index of the element to retrieve.

### Request Example
```javascript
// Playwright
const locator = mapLocator('layer[id=cities]').nth(2);
await locator.click();
```

```javascript
// Cypress
cy.mapLocator('layer[id=cities]').eq<MapLocator>(2).then((locator) => locator.click());
```

### Response
Returns a locator object for the nth matching element.
```

--------------------------------

### Take Screenshot (Playwright)

Source: https://mapgrab.github.io/docs/API/locator

The `.screenshot()` method captures a screenshot of a specific map element. It accepts options like padding and background color. The result can be compared against a snapshot.

```typescript
test("foo test", async ({ mapLocator }) => {
  const snap = await mapLocator('layer[id=cities]').first().screenshot({ padding: 11, backgroundColor: 'red' });

  await expect(snap).toMatchSnapshot('cities.png');
  ...
});
```

--------------------------------

### Set Map View by Lng/Lat (Cypress)

Source: https://mapgrab.github.io/docs/API/controller

Sets the map view to a specific center point defined by longitude and latitude using Cypress.

```javascript
it('foo test', () => {
  cy.mapController('mainMap').then((controller) => {
    controller.setView({ center: [11, 12] });
  });
});
```

--------------------------------

### Double Click Element (Cypress)

Source: https://mapgrab.github.io/docs/API/locator

In Cypress, `.dblclick()` is used to perform a double-click on a map element. This is equivalent to two consecutive single clicks.

```typescript
it('foo test', () => {
  cy.mapLocator('layer[id=cities]')
    .first()
    .then((locator) => locator.dblclick());
});
```

--------------------------------

### Fit Map to Element Bounds (Playwright)

Source: https://mapgrab.github.io/docs/API/locator

The `.fitMap()` method adjusts the map view to encompass the bounding box of the selected element. Use this to ensure a specific element is visible.

```typescript
test("foo test", async ({ mapLocator }) => {
  await mapLocator('layer[id=cities]').first().fitMap();
  ...
});
```

--------------------------------

### merge(property?)

Source: https://mapgrab.github.io/docs/API/locator

Returns a locator that merges all elements matched by the current locator, optionally merging by a specific property.

```APIDOC
## merge(property?)

### Description
Returns merged all elements matched to locator.

### Method
Chained method after a mapLocator call.

### Parameters
* **property** (string) - Optional - The property to merge by.

### Request Example
```javascript
// Playwright
const locator = mapLocator('layer[id=cities]').merge(); // Merge all cities
const locator2 = mapLocator('layer[id=cities]').merge('countryCode').last(); //Merge city by property: countryCode;

await locator.click();
await locator2.click();
```

```javascript
// Cypress
cy.mapLocator('layer[id=cities]').merge().then((locator) => locator.click());
```

### Response
Returns a locator object representing the merged elements.
```

--------------------------------

### exposeLayers

Source: https://mapgrab.github.io/docs/API/controller

Hides all layers on the map except for the ones specified. Supports Playwright and Cypress.

```APIDOC
## exposeLayers

### Description
Hides all layers on the map except for the ones specified.

### Usage
- playwright
- cypress

### Parameters
#### Request Body
- **layersToShow** (Array<string>) - Required - An array of layer IDs to be shown.

### Example (Playwright)
```javascript
test("foo test", async ({ mapController, mapLocator }) => {
  const controller = mapController('mainMap');

  await controller.exposeLayers(['cities-label']);

  await expect(await page.screenshot()).toMatchSnapshot('page-with-show-city-label.png');
  // ...
});
```

### Example (Cypress)
```javascript
it('foo test', () => {
  cy.mapController('mainMap').then((controller) => {
    controller.exposeLayers(['cities-label']);
  });
});
```
```

--------------------------------

### Wait for Map to Stabilize (Cypress)

Source: https://mapgrab.github.io/docs/API/controller

Waits for the map to stop painting or moving using Cypress. This ensures that any ongoing map animations have completed before proceeding.

```javascript
it('foo test', () => {
  cy.mapController('mainMap').then((controller) => {
    return controller.waitToMapStable();
  });
});

```

--------------------------------

### unprojectLngLatToScreenPoint

Source: https://mapgrab.github.io/docs/API/controller

Converts screen coordinates (x, y) to geographic coordinates (lng, lat). This is useful for translating user interface interactions into map data points.

```APIDOC
## unprojectLngLatToScreenPoint

### Description
Converts screen coordinates to geographic coordinates.

### Method
Not applicable (SDK method)

### Endpoint
Not applicable (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **x** (number) - Required - The x-coordinate on the screen.
- **y** (number) - Required - The y-coordinate on the screen.

### Request Example
```javascript
controller.unprojectLngLatToScreenPoint({ x: 200, y: 200 })
```

### Response
#### Success Response
- **lng** (number) - The longitude.
- **lat** (number) - The latitude.

#### Response Example
```json
{
  "lng": 22,
  "lat": 45
}
```
```

--------------------------------

### Click Element (Playwright)

Source: https://mapgrab.github.io/docs/API/locator

The `.click()` method simulates a click action on the selected map element. This is a fundamental interaction method.

```typescript
test("foo test", async ({ mapLocator }) => {
  await mapLocator('layer[id=cities]').first().click();
  ...
});
```

--------------------------------

### Wait for Map Repaint (Cypress)

Source: https://mapgrab.github.io/docs/API/controller

Waits for the map to complete a repaint cycle using Cypress. This ensures that visual updates triggered by user interactions are fully rendered.

```javascript
it('foo test', () => {
  cy.mapController('mainMap').then((controller) => {
    return controller.waitToMapRepaint();
  });
});

```

--------------------------------

### Expose Specific Layers (Cypress)

Source: https://mapgrab.github.io/docs/API/controller

Hides all layers on the map except for the ones specified by their IDs using Cypress. Useful for isolating specific map elements for testing.

```javascript
it('foo test', () => {
  cy.mapController('mainMap').then((controller) => {
    controller.exposeLayers(['cities-label']);
  });
});
```

--------------------------------

### MapGrab Selector with Partial Matching

Source: https://mapgrab.github.io/docs/selector

This selector demonstrates using partial matching for map and layer IDs. It finds elements on maps whose IDs contain 'mainMap' and on layers whose IDs contain 'cities-label'. Use this for flexible matching when exact IDs are not known or when dealing with dynamic naming conventions.

```selector
map[id*=mainMap] layer[id*=cities-label]  
```

--------------------------------

### Set Map View by Lng/Lat (Playwright)

Source: https://mapgrab.github.io/docs/API/controller

Sets the map view to a specific center point defined by longitude and latitude using Playwright.

```typescript
test("foo test", async ({ mapController }) => {
  await mapController('mainMap').setView({ center: [11, 12] })
  ...
});
```

--------------------------------

### Double Click Element (Playwright)

Source: https://mapgrab.github.io/docs/API/locator

Simulate a double-click action on a map element using `.dblclick()`. This is useful for interactions that require two rapid clicks.

```typescript
test("foo test", async ({ mapLocator }) => {
  await mapLocator('layer[id=cities]').first().dblclick();
  ...
});
```

--------------------------------

### waitToMapRepaint

Source: https://mapgrab.github.io/docs/API/controller

Waits for the map to complete a repaint cycle. This is typically used after an action that might trigger a visual update on the map, ensuring the update is reflected before proceeding.

```APIDOC
## waitToMapRepaint

### Description
Waits for the map to repaint.

### Method
Not applicable (SDK method)

### Endpoint
Not applicable (SDK method)

### Parameters
None

### Request Example
```javascript
controller.waitToMapRepaint()
```

### Response
#### Success Response
None

#### Response Example
None
```

--------------------------------

### enableInspector

Source: https://mapgrab.github.io/docs/API/controller

Enables the MapGrab inspector for the map. This method is available for both Playwright and Cypress testing frameworks.

```APIDOC
## enableInspector

### Description
Enables the MapGrab inspector for the map.

### Usage
- playwright
- cypress

### Example (Playwright)
```javascript
test("foo test", async ({ mapController }) => {
  await mapController('mainMap').enableInspector();
  // ...
});
```

### Example (Cypress)
```javascript
it('foo test', () => {
  cy.mapController('mainMap').then((controller) => {
    controller.enableInspector();
  });
});
```
```

--------------------------------

### last()

Source: https://mapgrab.github.io/docs/API/locator

Returns a locator for the last matching element found by the selector.

```APIDOC
## last()

### Description
Returns a locator to the last matching element.

### Method
Chained method after a mapLocator call.

### Parameters
None

### Request Example
```javascript
// Playwright
const locator = mapLocator('layer[id=cities]').last();
await locator.click();
```

```javascript
// Cypress
cy.mapLocator('layer[id=cities]').last<MapLocator>().then((locator) => locator.click());
```

### Response
Returns a locator object for the last matching element.
```

--------------------------------

### Convert Screen Point to Geographic Coordinates (Cypress)

Source: https://mapgrab.github.io/docs/API/controller

Converts screen coordinates (pixels) to geographic longitude and latitude using Cypress. This is useful for translating screen positions to map coordinates within Cypress tests.

```javascript
it('foo test', () => {
  cy.mapController('mainMap').then((controller) => {
    controller.unprojectLngLatToScreenPoint({ x: 200, y: 200 }).then(({ lat, lng }) => {
      ...
    });
  });
});

```

--------------------------------

### revertExposeLayers

Source: https://mapgrab.github.io/docs/API/controller

Restores the previous state of layer visibility after using `exposeLayers`. Supports Playwright and Cypress.

```APIDOC
## revertExposeLayers

### Description
Restores the previous state of layer visibility.

### Usage
- playwright
- cypress

### Parameters
#### Request Body
- **exposeState** (object) - Required - The state object returned by a previous `exposeLayers` call, used to revert to the original layer visibility.

### Example (Playwright)
```javascript
test("foo test", async ({ mapController, mapLocator }) => {
  const controller = mapController('mainMap');

  const exposeState = await controller.exposeLayers(['cities-label']);

  await expect(await page.screenshot()).toMatchSnapshot('page-with-show-city-label.png');

  await controller.revertExposeLayers(exposeState);
  // ...
});
```

### Example (Cypress)
```javascript
it('foo test', () => {
  cy.mapController('mainMap').then((controller) => {
    controller.exposeLayers(['countries-label'], ['countries-fill']).then((state) => {
      controller.revertExposeLayers(state);
    });
  });
});
```
```

--------------------------------

### Wait for Map to Load (Playwright)

Source: https://mapgrab.github.io/docs/API/controller

Waits until the map has finished loading. Use this to ensure all map tiles and data are ready before performing further actions.

```typescript
test("foo test", async ({ mapController, mapLocator, page }) => {
  await mapController('mainMap').waitToMapLoaded();
  ...
});

```

--------------------------------

### Click Element (Cypress)

Source: https://mapgrab.github.io/docs/API/locator

Use `.click()` in Cypress to perform a click on a map element. This method is straightforward for triggering click events.

```typescript
it('foo test', () => {
  cy.mapLocator('layer[id=cities]')
    .first()
    .then((locator) => locator.click());
});
```

--------------------------------

### Wait for Map to Stabilize (Playwright)

Source: https://mapgrab.github.io/docs/API/controller

Waits for the map to stop painting or moving. Use this after interactions that might cause map animations or updates to ensure the map is visually stable.

```typescript
test("foo test", async ({ mapController, mapLocator, page }) => {
  await mapController('mainMap').waitToMapStable();
  await expect(await page.screenshot()).toMatchSnapshot('map-loaded.png');
  ...
});

```

--------------------------------

### Enable MapGrab Inspector (Playwright)

Source: https://mapgrab.github.io/docs/API/controller

Enables the MapGrab inspector for a specific map instance using Playwright.

```typescript
test("foo test", async ({ mapController }) => {
  await mapController('mainMap').enableInspector();
  ...
});
```

--------------------------------

### getMapInstance

Source: https://mapgrab.github.io/docs/API/controller

Retrieves the underlying Mapbox GL JS or Maplibre GL JS map instance. This allows for direct interaction with the map object using its native methods.

```APIDOC
## getMapInstance

### Description
Get map handle its Mapbox GL JS or Maplibre GL JS instance.

### Method
Not applicable (SDK method)

### Endpoint
Not applicable (SDK method)

### Parameters
None

### Request Example
```javascript
controller.getMapInstance()
```

### Response
#### Success Response
- **map** (object) - The Mapbox GL JS or Maplibre GL JS map instance.

#### Response Example
```json
{
  "map": { /* Map instance object */ }
}
```
```

--------------------------------

### Merge Matching Elements (Cypress)

Source: https://mapgrab.github.io/docs/API/locator

Use `.merge()` in Cypress to combine all matching elements. This can be used to select a single merged element or to perform actions on the entire set.

```typescript
it('foo test', () => {
  cy.mapLocator('layer[id=cities]')
    .merge()
    .then((locator) => locator.click());
});
```

--------------------------------

### Set Map View by Screen Point (Playwright)

Source: https://mapgrab.github.io/docs/API/controller

Sets the map view to a specific center point defined by screen x/y coordinates using Playwright.

```typescript
test("foo test", async ({ mapController }) => {
  await mapController('mainMap').setViewAbsolute({ center: [240, 321] });
  ...
});
```

--------------------------------

### Wait for Map Repaint (Playwright)

Source: https://mapgrab.github.io/docs/API/controller

Waits for the map to complete a repaint cycle. This is useful after triggering visual changes on the map to ensure they are fully rendered.

```typescript
test("foo test", async ({ mapController, mapLocator, page }) => {
  await Promise.all([
    page.locator('.show-cities').click(),
    mapController('mainMap').waitToMapRepaint()
  ]);
  ...
});

```

--------------------------------

### Revert Layer Expose State (Playwright)

Source: https://mapgrab.github.io/docs/API/controller

Restores the previous state of layer visibility after using exposeLayers, using Playwright. Requires the state returned from exposeLayers.

```typescript
test("foo test", async ({ mapController, mapLocator }) => {
  const controller = mapController('mainMap');
    
  const exposeState = await controller.exposeLayers(['cities-label']);
  
  await expect(await page.screenshot()).toMatchSnapshot('page-with-show-city-label.png');
  
  await controller.revertExposeLayers(exposeState);
  ...
});
```

--------------------------------

### Merge Matching Elements (Playwright)

Source: https://mapgrab.github.io/docs/API/locator

The `.merge()` method combines all elements matching the locator into a single locator. It can optionally merge based on a property, like `countryCode`, and then select the last of the merged elements.

```typescript
test("foo test", async ({ mapLocator }) => {
  const locator = mapLocator('layer[id=cities]').merge(); // Merge all cities
  const locator2 = mapLocator('layer[id=cities]').merge('countryCode').last(); //Merge city by property: countryCode;

  await locator.click();
  await locator2.click();
  ...
});
```

--------------------------------

### Convert Screen Point to Geographic Coordinates (Playwright)

Source: https://mapgrab.github.io/docs/API/controller

Converts screen coordinates (pixels) to geographic longitude and latitude. Use this when you need to translate a point on the screen to its corresponding map location.

```typescript
test("foo test", async ({ mapController, mapLocator, page }) => {
  const controller = mapController('mainMap');
    
  const { lng, lat } = await controller.unprojectLngLatToScreenPoint({ x: 200, y: 200 });
  
  await expect(lng).toBe(22);
  ...
});

```

--------------------------------

### waitToMapStable

Source: https://mapgrab.github.io/docs/API/controller

Waits for the map to stop painting or moving, indicating that all animations or transitions have completed. This is useful for capturing screenshots or performing actions after the map has settled.

```APIDOC
## waitToMapStable

### Description
Waits for the map to stop painting or moving.

### Method
Not applicable (SDK method)

### Endpoint
Not applicable (SDK method)

### Parameters
None

### Request Example
```javascript
controller.waitToMapStable()
```

### Response
#### Success Response
None

#### Response Example
None
```

--------------------------------

### Expose Specific Layers (Playwright)

Source: https://mapgrab.github.io/docs/API/controller

Hides all layers on the map except for the ones specified by their IDs using Playwright. Useful for isolating specific map elements for testing.

```typescript
test("foo test", async ({ mapController, mapLocator }) => {
  const controller = mapController('mainMap');

  await controller.exposeLayers(['cities-label']);

  await expect(await page.screenshot()).toMatchSnapshot('page-with-show-city-label.png');
  ...
});
```

--------------------------------

### MapGrab Selector with Map, Layer, and Filter

Source: https://mapgrab.github.io/docs/selector

This selector targets an element within a specific map and layer, with an additional filter applied. Use this when you need to pinpoint a feature based on its map, layer, and a specific property value.

```selector
map[id=mainMap] layer[id=cities-label] filter["==", ["get", "id"], "123"]  
```

--------------------------------

### MapGrab Selector with Layer Only

Source: https://mapgrab.github.io/docs/selector

This selector retrieves all elements from any map that reside on a layer with the specified ID. Use this when the map origin is not critical, but the layer is.

```selector
layer[id=cities-label]  
```

--------------------------------

### MapGrab Selector with Map Only

Source: https://mapgrab.github.io/docs/selector

This selector targets all elements within a specific map, regardless of their layer. Use this when you need to access all features of a particular map.

```selector
map[id=mainMap]  
```

--------------------------------

### Disable MapGrab Inspector (Cypress)

Source: https://mapgrab.github.io/docs/API/controller

Disables the MapGrab inspector for a specific map instance using Cypress.

```javascript
it('foo test', () => {
  cy.mapController('mainMap').then((controller) => {
    controller.disableInspector();
  });
});
```

--------------------------------

### MapGrab Selector with Filter Only

Source: https://mapgrab.github.io/docs/selector

This selector retrieves all elements that have a specific property matching the given value, across all maps and layers. Use this when you need to find features based on a property value without regard to their location on the map.

```selector
filter["==", ["get", "id"], "123"]  
```

--------------------------------

### disableInspector

Source: https://mapgrab.github.io/docs/API/controller

Disables the MapGrab inspector for the map. This method is available for both Playwright and Cypress testing frameworks.

```APIDOC
## disableInspector

### Description
Disables the MapGrab inspector for the map.

### Usage
- playwright
- cypress

### Example (Playwright)
```javascript
test("foo test", async ({ mapController }) => {
  await mapController('mainMap').disableInspector();
  // ...
});
```

### Example (Cypress)
```javascript
it('foo test', () => {
  cy.mapController('mainMap').then((controller) => {
    controller.disableInspector();
  });
});
```
```

--------------------------------

### Disable MapGrab Inspector (Playwright)

Source: https://mapgrab.github.io/docs/API/controller

Disables the MapGrab inspector for a specific map instance using Playwright.

```typescript
test("foo test", async ({ mapController }) => {
  await mapController('mainMap').disableInspector();
  ...
});
```
Tokens:
Raw