Skip to content

Commit

Permalink
feat(TS): move types from DefinitelyTyped (#148)
Browse files Browse the repository at this point in the history
Co-authored-by: Kent C. Dodds <me+github@kentcdodds.com>

BREAKING CHANGE: TypeScript type definitions have been brought into this module and no longer needs to be referenced from DefinitelyTyped
  • Loading branch information
TheGallery authored and kentcdodds committed Aug 22, 2020
1 parent ae925b4 commit 55ba88b
Show file tree
Hide file tree
Showing 7 changed files with 280 additions and 17 deletions.
29 changes: 17 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,10 +58,13 @@ This allows you to use all the useful
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->


- [Installation](#installation)
- [With TypeScript](#with-typescript)
- [Intellisense for JavaScript with VS Code](#intellisense-for-javascript-with-vs-code)
- [Usage](#usage)
- [Differences from DOM Testing Library](#differences-from-dom-testing-library)
- [Config testIdAttribute](#config-testidattribute)
- [Other Solutions](#other-solutions)
- [Contributors](#contributors)
- [LICENSE](#license)
Expand All @@ -79,21 +82,21 @@ npm install --save-dev @testing-library/cypress

### With TypeScript

Typings are defined in `@types/testing-library__cypress` at
[DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/testing-library__cypress),
and should be added as follows in `tsconfig.json`:
Typings should be added as follows in `tsconfig.json`:

```json
{
"compilerOptions": {
"types": ["cypress", "@types/testing-library__cypress"]
"types": ["cypress", "@testing-library/cypress"]
}
}
```

### Intellisense for JavaScript with VS Code

If you're not using TypeScript, you use VS Code, and want to have code-completion with the methods from this library, simply add the following line to your project's root-level `jsconfig.json` file:
If you're not using TypeScript, you use VS Code, and want to have
code-completion with the methods from this library, simply add the following
line to your project's root-level `jsconfig.json` file:

```json
{
Expand All @@ -116,7 +119,7 @@ commands.
[See the `DOM Testing Library` docs for reference](https://testing-library.com)

You can find
[all Library definitions here](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/testing-library__cypress/index.d.ts).
[all Library definitions here](https://github.com/testing-library/cypress-testing-library/tree/master/types/index.d.ts).

To configure DOM Testing Library, use the following custom command:

Expand All @@ -134,9 +137,7 @@ cy.findAllByLabelText('Label text', {timeout: 7000}).should('exist')
cy.findAllByText('Jackie Chan').click()

// findAllByText _inside_ a form element
cy.get('form')
.findAllByText('Button Text')
.should('exist')
cy.get('form').findAllByText('Button Text').should('exist')
```

### Differences from DOM Testing Library
Expand Down Expand Up @@ -177,14 +178,16 @@ cy.findByText('Some Text').should('exist')

## Config testIdAttribute

If you would like to change the default testId from `data-testId` to `data-test-id`, add to your project's `cypress/support/index.js`:
If you would like to change the default testId from `data-testId` to
`data-test-id`, add to your project's `cypress/support/index.js`:

```javascript
import {configure} from '@testing-library/cypress'
configure({testIdAttribute: 'data-test-id'})
```

It accepts all configurations listed in [DOM testing library](https://testing-library.com/docs/dom-testing-library/api-configuration).
It accepts all configurations listed in
[DOM testing library](https://testing-library.com/docs/dom-testing-library/api-configuration).

## Other Solutions

Expand Down Expand Up @@ -247,6 +250,7 @@ Thanks goes to these people ([emoji key][emojis]):

<!-- markdownlint-enable -->
<!-- prettier-ignore-end -->

<!-- ALL-CONTRIBUTORS-LIST:END -->

This project follows the [all-contributors][all-contributors] specification.
Expand Down Expand Up @@ -297,5 +301,6 @@ MIT
[all-contributors]: https://github.com/all-contributors/all-contributors
[dom-testing-library]: https://github.com/testing-library/dom-testing-library
[cypress]: https://www.cypress.io/
[discord-badge]: https://img.shields.io/discord/723559267868737556.svg?color=7389D8&labelColor=6A7EC2&logo=discord&logoColor=ffffff&style=flat-square
[discord-badge]:
https://img.shields.io/discord/723559267868737556.svg?color=7389D8&labelColor=6A7EC2&logo=discord&logoColor=ffffff&style=flat-square
[discord]: https://discord.gg/c6JN9fM
14 changes: 9 additions & 5 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
"version": "0.0.0-semantically-released",
"description": "Simple and complete custom Cypress commands and utilities that encourage good testing practices.",
"main": "dist/index.js",
"types": "types/index.d.ts",
"engines": {
"node": ">=10",
"npm": ">=6"
Expand All @@ -18,11 +19,13 @@
"test:cypress:run": "cypress run",
"test:unit": "kcd-scripts test --no-watch",
"test:unit:watch": "kcd-scripts test",
"validate": "kcd-scripts validate build,lint,test"
"typecheck": "dtslint ./types/",
"validate": "kcd-scripts validate build,lint,test,typecheck"
},
"files": [
"dist",
"add-commands.js"
"add-commands.js",
"types"
],
"keywords": [
"testing",
Expand All @@ -38,13 +41,14 @@
"license": "MIT",
"dependencies": {
"@babel/runtime": "^7.11.2",
"@testing-library/dom": "^7.22.2",
"@types/testing-library__cypress": "^5.0.6"
"@testing-library/dom": "^7.22.2"
},
"devDependencies": {
"cypress": "^5.0.0",
"dtslint": "^3.6.14",
"kcd-scripts": "^6.2.4",
"npm-run-all": "^4.1.5"
"npm-run-all": "^4.1.5",
"typescript": "^4.0.2"
},
"peerDependencies": {
"cypress": "^2.1.0 || ^3.0.0 || ^4.0.0 || ^5.0.0"
Expand Down
2 changes: 2 additions & 0 deletions types/add-commands.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
// Allow `import '@testing-library/cypress/add-commands'` from a `cypress/commands.ts` file
import './'
202 changes: 202 additions & 0 deletions types/index.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,202 @@
// TypeScript Version: 3.8

import {
configure,
Matcher,
MatcherOptions as DTLMatcherOptions,
ByRoleOptions as DTLByRoleOptions,
SelectorMatcherOptions as DTLSelectorMatcherOptions,
} from '@testing-library/dom'

export interface CTLMatcherOptions {
timeout?: number
container?: HTMLElement | JQuery
}

export type MatcherOptions = DTLMatcherOptions | CTLMatcherOptions
export type ByRoleOptions = DTLByRoleOptions | CTLMatcherOptions
export type SelectorMatcherOptions = DTLSelectorMatcherOptions | CTLMatcherOptions

declare global {
namespace Cypress {
interface Chainable<Subject = any> {
/**
* dom-testing-library helpers for Cypress
*
* `findBy*` APIs search for an element and throw an error if nothing found
* `findAllBy*` APIs search for all elements and an error if nothing found
*
* @see https://github.com/testing-library/cypress-testing-library#usage
* @see https://github.com/testing-library/dom-testing-library#table-of-contents
*/
findByPlaceholderText(id: Matcher, options?: MatcherOptions): Chainable<JQuery>

/**
* dom-testing-library helpers for Cypress
*
* `findBy*` APIs search for an element and throw an error if nothing found
* `findAllBy*` APIs search for all elements and an error if nothing found
*
* @see https://github.com/testing-library/cypress-testing-library#usage
* @see https://github.com/testing-library/dom-testing-library#table-of-contents
*/
findAllByPlaceholderText(id: Matcher, options?: MatcherOptions): Chainable<JQuery>

/**
* dom-testing-library helpers for Cypress
*
* `findBy*` APIs search for an element and throw an error if nothing found
* `findAllBy*` APIs search for all elements and an error if nothing found
*
* @see https://github.com/testing-library/cypress-testing-library#usage
* @see https://github.com/testing-library/dom-testing-library#table-of-contents
*/
findByText(id: Matcher, options?: SelectorMatcherOptions): Chainable<JQuery>

/**
* dom-testing-library helpers for Cypress
*
* `findBy*` APIs search for an element and throw an error if nothing found
* `findAllBy*` APIs search for all elements and an error if nothing found
*
* @see https://github.com/testing-library/cypress-testing-library#usage
* @see https://github.com/testing-library/dom-testing-library#table-of-contents
*/
findAllByText(id: Matcher, options?: SelectorMatcherOptions): Chainable<JQuery>

/**
* dom-testing-library helpers for Cypress
*
* `findBy*` APIs search for an element and throw an error if nothing found
* `findAllBy*` APIs search for all elements and an error if nothing found
*
* @see https://github.com/testing-library/cypress-testing-library#usage
* @see https://github.com/testing-library/dom-testing-library#table-of-contents
*/
findByLabelText(id: Matcher, options?: SelectorMatcherOptions): Chainable<JQuery>

/**
* dom-testing-library helpers for Cypress
*
* `findBy*` APIs search for an element and throw an error if nothing found
* `findAllBy*` APIs search for all elements and an error if nothing found
*
* @see https://github.com/testing-library/cypress-testing-library#usage
* @see https://github.com/testing-library/dom-testing-library#table-of-contents
*/
findAllByLabelText(id: Matcher, options?: SelectorMatcherOptions): Chainable<JQuery>

/**
* dom-testing-library helpers for Cypress
*
* `findBy*` APIs search for an element and throw an error if nothing found
* `findAllBy*` APIs search for all elements and an error if nothing found
*
* @see https://github.com/testing-library/cypress-testing-library#usage
* @see https://github.com/testing-library/dom-testing-library#table-of-contents
*/
findByAltText(id: Matcher, options?: MatcherOptions): Chainable<JQuery>

/**
* dom-testing-library helpers for Cypress
*
* `findBy*` APIs search for an element and throw an error if nothing found
* `findAllBy*` APIs search for all elements and an error if nothing found
*
* @see https://github.com/testing-library/cypress-testing-library#usage
* @see https://github.com/testing-library/dom-testing-library#table-of-contents
*/
findAllByAltText(id: Matcher, options?: MatcherOptions): Chainable<JQuery>

/**
* dom-testing-library helpers for Cypress
*
* `findBy*` APIs search for an element and throw an error if nothing found
* `findAllBy*` APIs search for all elements and an error if nothing found
*
* @see https://github.com/testing-library/cypress-testing-library#usage
* @see https://github.com/testing-library/dom-testing-library#table-of-contents
*/
findByTestId(id: Matcher, options?: MatcherOptions): Chainable<JQuery>

/**
* dom-testing-library helpers for Cypress
*
* `findBy*` APIs search for an element and throw an error if nothing found
* `findAllBy*` APIs search for all elements and an error if nothing found
*
* @see https://github.com/testing-library/cypress-testing-library#usage
* @see https://github.com/testing-library/dom-testing-library#table-of-contents
*/
findAllByTestId(id: Matcher, options?: MatcherOptions): Chainable<JQuery>

/**
* dom-testing-library helpers for Cypress
*
* `findBy*` APIs search for an element and throw an error if nothing found
* `findAllBy*` APIs search for all elements and an error if nothing found
*
* @see https://github.com/testing-library/cypress-testing-library#usage
* @see https://github.com/testing-library/dom-testing-library#table-of-contents
*/
findByTitle(id: Matcher, options?: MatcherOptions): Chainable<JQuery>

/**
* dom-testing-library helpers for Cypress
*
* `findBy*` APIs search for an element and throw an error if nothing found
* `findAllBy*` APIs search for all elements and an error if nothing found
*
* @see https://github.com/testing-library/cypress-testing-library#usage
* @see https://github.com/testing-library/dom-testing-library#table-of-contents
*/
findAllByTitle(id: Matcher, options?: MatcherOptions): Chainable<JQuery>

/**
* dom-testing-library helpers for Cypress
*
* `findBy*` APIs search for an element and throw an error if nothing found
* `findAllBy*` APIs search for all elements and an error if nothing found
*
* @see https://github.com/testing-library/cypress-testing-library#usage
* @see https://github.com/testing-library/dom-testing-library#table-of-contents
*/
findByDisplayValue(id: Matcher, options?: MatcherOptions): Chainable<JQuery>

/**
* dom-testing-library helpers for Cypress
*
* `findBy*` APIs search for an element and throw an error if nothing found
* `findAllBy*` APIs search for all elements and an error if nothing found
*
* @see https://github.com/testing-library/cypress-testing-library#usage
* @see https://github.com/testing-library/dom-testing-library#table-of-contents
*/
findAllByDisplayValue(id: Matcher, options?: MatcherOptions): Chainable<JQuery>

/**
* dom-testing-library helpers for Cypress
*
* `findBy*` APIs search for an element and throw an error if nothing found
* `findAllBy*` APIs search for all elements and an error if nothing found
*
* @see https://github.com/testing-library/cypress-testing-library#usage
* @see https://github.com/testing-library/dom-testing-library#table-of-contents
*/
findByRole(id: Matcher, options?: ByRoleOptions): Chainable<JQuery>

/**
* dom-testing-library helpers for Cypress
*
* `findBy*` APIs search for an element and throw an error if nothing found
* `findAllBy*` APIs search for all elements and an error if nothing found
*
* @see https://github.com/testing-library/cypress-testing-library#usage
* @see https://github.com/testing-library/dom-testing-library#table-of-contents
*/
findAllByRole(id: Matcher, options?: ByRoleOptions): Chainable<JQuery>
}
}
}

export { configure }
25 changes: 25 additions & 0 deletions types/test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
/// <reference types="Cypress" />
import { configure } from '@testing-library/cypress'
import '@testing-library/cypress/add-commands'

configure({ testIdAttribute: 'data-myown-testid' })

// findBy*
cy.findByPlaceholderText('foo') // $ExpectType Chainable<JQuery<HTMLElement>>
cy.findByText('foo') // $ExpectType Chainable<JQuery<HTMLElement>>
cy.findByLabelText('foo') // $ExpectType Chainable<JQuery<HTMLElement>>
cy.findByAltText('foo') // $ExpectType Chainable<JQuery<HTMLElement>>
cy.findByTestId('foo') // $ExpectType Chainable<JQuery<HTMLElement>>
cy.findByTitle('foo') // $ExpectType Chainable<JQuery<HTMLElement>>
cy.findByDisplayValue('foo') // $ExpectType Chainable<JQuery<HTMLElement>>
cy.findByRole('foo') // $ExpectType Chainable<JQuery<HTMLElement>>

// findAllBy*
cy.findAllByPlaceholderText('foo') // $ExpectType Chainable<JQuery<HTMLElement>>
cy.findAllByText('foo') // $ExpectType Chainable<JQuery<HTMLElement>>
cy.findAllByLabelText('foo') // $ExpectType Chainable<JQuery<HTMLElement>>
cy.findAllByAltText('foo') // $ExpectType Chainable<JQuery<HTMLElement>>
cy.findAllByTestId('foo') // $ExpectType Chainable<JQuery<HTMLElement>>
cy.findAllByTitle('foo') // $ExpectType Chainable<JQuery<HTMLElement>>
cy.findAllByDisplayValue('foo') // $ExpectType Chainable<JQuery<HTMLElement>>
cy.findAllByRole('foo') // $ExpectType Chainable<JQuery<HTMLElement>>
16 changes: 16 additions & 0 deletions types/tsconfig.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
{
"compilerOptions": {
"module": "commonjs",
"lib": ["es6", "dom"],
"noImplicitAny": true,
"noImplicitThis": true,
"strictFunctionTypes": true,
"strictNullChecks": true,
"baseUrl": ".",
"noEmit": true,
"types": [],
"paths": {
"@testing-library/cypress": ["."]
}
}
}
9 changes: 9 additions & 0 deletions types/tslint.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{
"extends": ["dtslint/dtslint.json"],
"rules": {
"no-useless-files": false,
"no-relative-import-in-test": false,
"semicolon": false,
"whitespace": false
}
}

0 comments on commit 55ba88b

Please sign in to comment.