---
permalink: /plugins/customLocator
editLink: false
sidebar: auto
title: customLocator
---

<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

## customLocator

Creates a [custom locator][1] by using special attributes in HTML.

If you have a convention to use `data-test-id` or `data-qa` attributes to mark active elements for e2e tests,
you can enable this plugin to simplify matching elements with these attributes:

```js
// replace this:
I.click({ css: '[data-test-id=register_button]');
// with this:
I.click('$register_button');
```

This plugin will create a valid XPath locator for you.

#### Configuration

*   `enabled` (default: `false`) should a locator be enabled
*   `prefix` (default: `$`) sets a prefix for a custom locator.
*   `attribute` (default: `data-test-id`) to set an attribute to be matched.
*   `strategy` (default: `xpath`) actual locator strategy to use in query (`css` or `xpath`).
*   `showActual` (default: false) show in the output actually produced XPath or CSS locator. By default shows custom locator value.

#### Examples:

Using `data-test` attribute with `$` prefix:

```js
// in codecept.conf.js
plugins: {
 customLocator: {
   enabled: true,
   attribute: 'data-test'
 }
}
```

In a test:

```js
I.seeElement('$user'); // matches => [data-test=user]
I.click('$sign-up'); // matches => [data-test=sign-up]
```

Using `data-qa` attribute with `=` prefix:

```js
// in codecept.conf.js
plugins: {
 customLocator: {
   enabled: true,
   prefix: '=',
   attribute: 'data-qa'
 }
}
```

In a test:

```js
I.seeElement('=user'); // matches => [data-qa=user]
I.click('=sign-up'); // matches => [data-qa=sign-up]
```

Using `data-qa` OR `data-test` attribute with `=` prefix:

```js
// in codecept.conf.js
plugins: {
 customLocator: {
   enabled: true,
   prefix: '=',
   attribute: ['data-qa', 'data-test'],
   strategy: 'xpath'
 }
}
```

In a test:

```js
I.seeElement('=user'); // matches => //*[@data-qa=user or @data-test=user]
I.click('=sign-up'); // matches => //*[data-qa=sign-up or @data-test=sign-up]
```

```js
// in codecept.conf.js
plugins: {
 customLocator: {
   enabled: true,
   prefix: '=',
   attribute: ['data-qa', 'data-test'],
   strategy: 'css'
 }
}
```

In a test:

```js
I.seeElement('=user'); // matches => [data-qa=user],[data-test=user]
I.click('=sign-up'); // matches => [data-qa=sign-up],[data-test=sign-up]
```

### Parameters

*   `config` &#x20;

[1]: https://codecept.io/locators#custom-locators