cypress-layout-inspector
[![Build Status][build-badge]][build]
[![Downloads per month][downloads-badge]][package]
[![version][version-badge]][package]
[![Semantic Release][semantic-badge]][semantic]
[![Watch on GitHub][github-watch-badge]][github-watch]
[![Star on GitHub][github-star-badge]][github-star]
[![Tweet][twitter-badge]][twitter]
## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [Configuration](#configuration)
- [Assertions](#assertions)
- [Alignment](#alignment)
- [Dimensions](#dimensions)
- [Positioning](#positioning)
- [Styling](#styling)
- [Contributors ✨](#contributors-)
## Installation
This module is distributed via [npm][npm] which is bundled with [node] and should be installed as one of your project's `devDependencies`:
```
npm install --save-dev cypress-layout-inspector
```
This has been tested thoroughly with the [Cypress.io][cypress-io] E2E test runner **v4.0.0+**
## Usage
`cypress-layout-inspector` extends the `chai` assertion library.
Add this line to your project's `cypress/support/e2e.js`:
```javascript
import "cypress-layout-inspector/add-support";
```
You can now use all of `cypress-layout-inspector`'s assertions.
To show some examples (from [cypress/e2e/position.spec.js](cypress/e2e/position.spec.js)):
```javascript
it("block-2 should be positioned right of block-1", () => {
cy.get(".block-2").should("be.rightOf", ".block-1", 50);
});
it("block-3 should be positioned left of block-4", () => {
cy.get(".block-3").should("be.leftOf", ".block-4", 50);
});
```
## Configuration
To configure `cypress-layout-inspector`, use the following custom command:
```javascript
cy.configureLayoutInspector(config);
```
`cypress-layout-inspector` uses `getBoundingClientRect()` behind the scenes which returns size equal to an elements (width/height + padding + border-width) in the case that the standard box model is being used, or (width/height) only if box-sizing: border-box has been set on it.
If you would like to use the standard box model but exclude padding in the total you can achieve this by doing the following:
```javascript
before(() => {
cy.configureLayoutInspector({
excludePadding: true,
threshold: 5,
});
});
```
## Assertions
### Alignment
#### `horizontallyAligned(element[, edge])`
| argument | type | options | default |
| ----------- | ------ | ------------------------------------ | ------- |
| **element** | string | - | - |
| **edge** | string | `'top', 'bottom', 'centered', 'all'` | `'all'` |
#### `verticallyAligned(element[, edge])`
| argument | type | options | default |
| ----------- | ------ | ------------------------------------ | ------- |
| **element** | string | - | - |
| **edge** | string | `'left', 'right', 'centered', 'all'` | `'all'` |
#### `overflowing([, direction])`
| argument | type | options | default |
| ------------- | ------ | ------------------------------------- | ------- |
| **direction** | string | `'vertically', 'horizontally', 'any'` | `'any'` |
#### `overlapping(element)`
| argument | type | options | default |
| ----------- | ------ | ------- | ------- |
| **element** | string | - | - |
### Dimensions
The following width and height assertions are chain-able and can be used with the .gt, .within and .lt methods
#### `width(measure)`
#### `height(measure)`
| argument | type | options | default |
| ----------- | ------ | ------- | ------- |
| **measure** | number | - | - |
### Positioning
The following assertions will check an elements distance is >= 0 if no distance is set
#### `rightOf(element[, distance])`
#### `leftOf(element[, distance])`
#### `above(element[, distance])`
#### `below(element[, distance])`
| argument | type | options | default |
| ------------ | ------ | ------- | ------- |
| **element** | string | - | - |
| **distance** | number | - | - |
#### `inside(element[, distances { top, left, bottom, right }])`
| argument | type | options | default |
| ------------- | ------ | ------- | ------- |
| **element** | string | - | - |
| **distances** | object | - | - |
### Styling
#### `style(property, value)`
| argument | type | options | default |
| ------------ | ------ | ------- | ------- |
| **property** | string | - | - |
| **value** | string | - | - |
## Contributors ✨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
[npm]: https://www.npmjs.com/
[node]: https://www.nodejs.org/
[cypress-io]: https://www.cypress.io/
[build-badge]: https://img.shields.io/github/workflow/status/msmps/cypress-layout-inspector/cypress-layout-inspector%20tests?style=flat-square
[build]: https://github.com/msmps/cypress-layout-inspector/actions
[version-badge]: https://img.shields.io/npm/v/cypress-layout-inspector?style=flat-square
[package]: https://www.npmjs.com/package/cypress-layout-inspector
[downloads-badge]: https://img.shields.io/npm/dm/cypress-layout-inspector?style=flat-square
[semantic-badge]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=flat-square
[semantic]: https://github.com/semantic-release/semantic-release
[github-watch-badge]: https://img.shields.io/github/watchers/msmps/cypress-layout-inspector.svg?style=social
[github-watch]: https://github.com/msmps/cypress-layout-inspector/watchers
[github-star-badge]: https://img.shields.io/github/stars/msmps/cypress-layout-inspector.svg?style=social
[github-star]: https://github.com/msmps/cypress-layout-inspector/stargazers
[twitter]: https://twitter.com/intent/tweet?text=Check%20out%20cypress-layout-inspector%20by%20%40msmps_%20https%3A%2F%2Fgithub.com%2Fmsmps%2Fcypress-layout-inspector%20%F0%9F%95%B5%EF%B8%8F%E2%80%8D%E2%99%82%EF%B8%8F
[twitter-badge]: https://img.shields.io/twitter/url/https/github.com/msmps/cypress-layout-inspector.svg?style=social
