# @hackney/mtfh-cypress

> Cypress helpers for LBH Modern Tools for Housing

Latest version **1.3.2** (published 2026-07-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install @hackney/mtfh-cypress
pnpm add @hackney/mtfh-cypress
yarn add @hackney/mtfh-cypress
bun add @hackney/mtfh-cypress
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.3.2 |
| Published | 2026-07-23 |
| First published | 2021-11-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 80.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1 |
| Author | Gareth Cozens |
| Maintainers | makeyw, selwyn.preston, lbhtkarki, mpederiva, humulla, seadrumsquid |

## Links

- npm: https://www.npmjs.com/package/@hackney/mtfh-cypress
- Repository: https://github.com/LBHackney-IT/mtfh-frontend
- Homepage: https://github.com/LBHackney-IT/mtfh-frontend#readme
- Issues: https://github.com/LBHackney-IT/mtfh-frontend/issues
- npm.io page: https://npm.io/package/@hackney/mtfh-cypress

## Dependencies (5)

- [pa11y](https://npm.io/package/pa11y.md) ^9.1.1
- [puppeteer](https://npm.io/package/puppeteer.md) ^24.37.5
- [lighthouse](https://npm.io/package/lighthouse.md) ^13.4.0
- [cypress-terminal-report](https://npm.io/package/cypress-terminal-report.md) ^6.1.0
- [@testing-library/cypress](https://npm.io/package/@testing-library/cypress.md) ^10.0.2

## Recent versions

- 1.3.2 (latest) — 2026-07-23
- 1.3.1 — 2026-07-23
- 1.3.0 — 2026-07-21
- 1.2.1 — 2021-12-07
- 1.2.0 — 2021-12-06
- 1.1.0 — 2021-12-03
- 1.0.0 — 2021-11-09

## README

# `@hackney/mtfh-cypress`

Cypress helpers for Modern Tools for Housing. Intended for use with a live environment
that resolves micro-frontends via import maps: it stubs the import map with the URL from
the env so you can test a local MFE against that environment without deploying.

Requires **Cypress 13+** and **Node.js 24+**.

Lifecycle:

1. Before All hook visits the baseURL as an authenticated Hackney user to intercept
   configuration (feature toggles) and store as a fixture.
2. Do a request to `${DEV_URL}/import-map.json` and store the output.
3. Before Each hook will intercept all import-map.json requests and determine which
   import-map to stub with the DEV_URL payload.

## Installation

```bash
npm install @hackney/mtfh-cypress
npm install -D dotenv cypress@^13
```

## Usage

This library provides both a configuration plugin as well as a collection of hooks and
commands. Plugins run in the Node context within Cypress and commands run in the browser,
so we have to wire them up separately.

### Plugin

In `cypress.config.js` (Cypress 10+):

```js
const { defineConfig } = require("cypress");
const { configPlugin } = require("@hackney/mtfh-cypress/plugin");

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      return configPlugin(on, config);
    },
    env: {
      DEV_URL: "http://localhost:9000",
    },
  },
});
```

Create a `.env` file in the root of your project:

```
CYPRESS_ENVIRONMENT=development
CYPRESS_BASE_URL=https://manage-my-home-development.hackney.gov.uk
CYPRESS_AUTH_TOKEN=token
```

Configure these variables in your CI pipeline to match your environment.

### Hooks & Commands

In `cypress/support/e2e.js` (or `cypress/support/index.js`):

```js
import "@hackney/mtfh-cypress";
```

This will import the `@testing-library/cypress` commands to mirror the FE unit testing
approaches we use.

Commands added:

```js
// Visit a url with authenticated credentials
cy.authVisit("/", options);
// Visit a url as a guest (unauthenticated)
cy.guestVisit("/", options);
// Get the value of a feature toggle
cy.hasToggle("MMH.CreateTenure").then((bool) => {});
// Skip test on ENVIRONMENT env
cy.skipOnEnv("development");
// Skip test on Feature Toggle
cy.skipOnToggle("MMH.CreateTenure", true);
```

To skip a collection of tests encapsulate the tests in a `describe`:

```js
describe("Collection of tests", () => {
  before(() => {
    cy.skipOnToggle("MMH.CreateTenure", true);
  });

  it("creates a tenure", () => {
    // ...
  });
});
```

## Audits

We provide commands for performance and accessibility testing using **Lighthouse** and
**Pa11y** directly (no `@cypress-audit/*` packages).

```js
// Equivalent of testing for mobile
cy.lighthouse({
  seo: 0,
  "best-practices": 100,
  accessibility: 100,
  performance: 80,
});

// Runs lighthouse with the desktop config
cy.lighthouseDesktop({
  seo: 0,
  "best-practices": 100,
  accessibility: 100,
  performance: 80,
});

// Runs accessibility testing, using pa11y
cy.pa11y({ actions: ["wait for element h1 to be added"] });
```

NB: Lighthouse performance metrics from this plugin can't really be taken as an indication
of the live report. This package is intended to run a local version of the micro-frontend
so we can test against it before deploying — i.e. against an app that isn't served by our
architecture. You can use it as a quality gate so new changes don't reduce the scores. We
recommend manual performance testing in live environments for real-world values.

## Additions

This library comes with the following preconfigured:

- `@testing-library/cypress`
- `lighthouse` and `pa11y` (via custom Cypress tasks)
- `cypress-terminal-report`

## Configuration

The config plugin overrides a few Cypress defaults that align to the requirements more
closely, such as:

```js
{
  retries: {
    runMode: 2,
    openMode: 0,
  },
  chromeWebSecurity: false,
  defaultCommandTimeout: 10000,
}
```

---
_Source: https://npm.io/package/@hackney/mtfh-cypress · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._