https://github.com/appium/css-locator-to-native
Platform-agnostic CSS selector parsing and normalization for native locator transformation
https://github.com/appium/css-locator-to-native
Last synced: 4 days ago
JSON representation
Platform-agnostic CSS selector parsing and normalization for native locator transformation
- Host: GitHub
- URL: https://github.com/appium/css-locator-to-native
- Owner: appium
- License: apache-2.0
- Created: 2026-06-07T16:33:22.000Z (29 days ago)
- Default Branch: main
- Last Pushed: 2026-06-07T18:52:02.000Z (29 days ago)
- Last Synced: 2026-06-07T20:12:26.476Z (29 days ago)
- Language: TypeScript
- Homepage:
- Size: 19.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# @appium/css-locator-to-native
Platform-agnostic CSS selector parsing and normalization for native locator transformation.
## Installation
```bash
npm install @appium/css-locator-to-native
```
## Quick start
```typescript
import {
createCssTransformer,
type AttributeSchema,
type ParsedSelector,
type StrategyKey,
} from '@appium/css-locator-to-native';
const schema: AttributeSchema = {
attributes: {
visible: {type: 'boolean'},
name: {type: 'string', aliases: ['id']},
index: {type: 'numeric', aliases: ['nth-child']},
},
booleanFormat: 'zero-one',
};
const emitters = {
native: {
strategy: 'my-native-strategy',
emit(parsed: ParsedSelector) {
// Map ParsedSelector IR to your platform's selector syntax
return parsed.rule.tag ?? '*';
},
},
};
const transformCss = createCssTransformer({
schema,
emitters,
resolveStrategy(): StrategyKey {
return 'native';
},
});
const {strategy, selector} = transformCss('window#foo[visible]');
// => { strategy: 'my-native-strategy', selector: '...' }
```
## API
Everything is exported from a single entry point:
| Export | Description |
|---|---|
| `normalizeCssSelector(css, schema)` | Parse and normalize a CSS selector into a `ParsedSelector` IR |
| `createCssTransformer(config)` | Returns a function that parses CSS and produces a `NativeLocator` |
| `InvalidSelectorError` | CSS syntax cannot be parsed |
| `UnsupportedSelectorError` | Parsed CSS uses unsupported features or unknown attributes |
| `UnresolvedStrategyError` | No matching emitter for the resolved strategy key |
### ParsedSelector IR
Normalization produces a platform-agnostic intermediate representation. The IR captures CSS structure — tags, classes, `#id`, attributes, pseudos, combinators — validated against your schema. It does **not** encode iOS class chain, UiAutomator, or any other native syntax.
```typescript
interface ParsedSelector {
rule: ParsedRule; // first comma-separated rule only
}
interface ParsedRule {
combinator?: 'descendant' | 'child';
tag?: string; // raw CSS tag (may be '*')
classes: string[]; // raw class tokens
id?: string; // raw #id value
attributes: ParsedAttribute[];
pseudos: ParsedAttribute[];
nested?: ParsedRule;
}
```
### Attribute schemas
Drivers declare which CSS attributes are valid and how booleans are coerced:
```typescript
interface AttributeSchema {
attributes: Record;
booleanFormat?: 'zero-one' | 'true-false' | 'literal';
}
```
- **`zero-one`** — `true`/`1`/empty → `'1'`, `false`/`0` → `'0'`
- **`true-false`** — `true`/empty → `'true'`, `false` → `'false'`
- **`literal`** (default) — keep the raw attribute value unchanged; implicit booleans (no value) stay unset
Tag, class, and `#id` mapping (e.g. `XCUIElementType*` prefixing, `resourceId` prefixing) is entirely the driver's responsibility in emitters.
### Multi-strategy routing
`createCssTransformer` requires a registry of `StrategyEmitter`s and a `resolveStrategy` callback. The resolver picks which emitter to use based on selector shape; the transformer returns both the target strategy name and the native selector string.
```typescript
interface NativeLocator {
strategy: string;
selector: string;
}
```
A driver with a single target strategy uses a one-entry registry and a trivial resolver.
## Driver integration pattern
Platform logic stays in the driver. A typical layout:
```
lib/css/
schema.ts # AttributeSchema for the platform
*-emitter.ts # StrategyEmitter implementations
resolve-helpers.ts # isSimpleIdSelector, etc.
index.ts # createCssTransformer wrapper
```
In `find` commands, use the strategy from the transform result instead of hardcoding it:
```typescript
if (strategy === 'css selector') {
({strategy, selector} = cssToNativeLocator(selector));
}
```
## Supported CSS subset
Matches the subset accepted by existing Appium drivers:
- Tags (including `*`), `#id`, classes, attribute selectors (`=`, `*=`, `^=`, `$=`, `~=`)
- Child (`>`) and descendant (space) combinators
- Pseudo-classes accepted as attributes per schema (e.g. `:visible`, `:nth-child(2)`)
- First comma-separated rule only (additional rules are ignored)
- Unsupported: `+` / `~` combinators, pseudo-elements, nesting (`&`), namespaces
## Development
```bash
npm install --no-package-lock
npm run typecheck # type-check lib + test
npm run build # compile to build/
npm test # unit tests (compiled ESM)
npm run lint
npm run format:check
```
## Requirements
- Node.js `^20.19.0 || ^22.12.0 || >=24.0.0`
- npm `>=10`
## License
[Apache-2.0](LICENSE)