Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/phimage/Erik

Erik is an headless browser based on WebKit. An headless browser allow to run functional tests, to access and manipulate webpages using javascript.
https://github.com/phimage/Erik

erik headless-browsers swift test webkit

Last synced: 3 months ago
JSON representation

Erik is an headless browser based on WebKit. An headless browser allow to run functional tests, to access and manipulate webpages using javascript.

Awesome Lists containing this project

README

        

# Erik

[![Join the chat at https://gitter.im/phimage/Erik](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/phimage/Erik?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat
)](http://mit-license.org) [![Platform](http://img.shields.io/badge/platform-ios_osx-lightgrey.svg?style=flat
)](https://developer.apple.com/resources/) [![Language](http://img.shields.io/badge/language-swift-orange.svg?style=flat
)](https://developer.apple.com/swift) [![Issues](https://img.shields.io/github/issues/phimage/Erik.svg?style=flat
)](https://github.com/phimage/Erik/issues) [![Cocoapod](http://img.shields.io/cocoapods/v/Erik.svg?style=flat)](http://cocoadocs.org/docsets/Erik/)[![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)


Become a Patron!


Buy me a coffee

[](#logo) Erik is a [headless browser](https://en.wikipedia.org/wiki/Headless_browser) based on [WebKit](https://fr.wikipedia.org/wiki/WebKit) and HTML parser [Kanna](https://github.com/tid-kijyun/Kanna).

An headless browser allow to run functional tests, to access and manipulate webpages using javascript.

```swift
let browser = Erik.visit(url: url) { document, error in
// browse HTML element, click, submit form and more
}
```

## Navigation
Go to an url
```swift
Erik.visit(url: url) { object, error in
if let e = error {

} else if let doc = object {
// HTML Inspection
}
}
```
How to get current url?
```swift
if let url = Erik.currentURL {..}
```

For multiple browsing you can create an instance of headless browser and use same functions
```swift
let browser = Erik()
browser.visitURL...
```

## HTML Inspection
### Search for nodes by [CSS selector](http://www.w3schools.com/cssref/css_selectors.asp)
```swift
for link in doc.querySelectorAll("a, link") {
print(link.text)
print(link["href"])
}
```
### Edit first input field with name "user"
```swift
if let input = doc.querySelectorAll("input[name=\"user\"]").first {
input["value"] = "Eric"
}
```

### Submit a form
```swift
if let form = doc.querySelector("form[id='search']") as? Form {
form.submit()
}
```

### Evaluate some JavaScript
```swift
let javaScriptSource = "console.log("test");"
Erik.evaluate(javaScript:javaScriptSource) { (obj, err) -> Void in
if let error = err {
switch error {
case ErikError.javaScriptError(let message):
print(message)
default :
print("\(error)")
}
}
else if let capturedValue = obj {
// do something according to result
}
}
```
`capturedValue` is the content of JavaScript variable `resultErik`
Affect this variable in your JavaScript code.
```swift
let javaScriptSource = "console.log('test'); var resultErik = 1 + 1;"
```

### Warning about DOM change
:warning: All action on Dom use JavaScript and do not modify the actual
`Document` object and its children `Element`.

You must use `currentContent` to get a refreshed `Document` object

### Get current content
```swift
Erik.currentContent { (obj, err) -> Void in
if let error = err {
}
else if let document = obj {
// HTML Inspection
}
}
```
### Using Future
As an optional feature, you can use [Future/Promise](https://en.wikipedia.org/wiki/Futures_and_promises) ( Erik use frameworks [BrightFutures](https://github.com/Thomvis/BrightFutures) & [Result](https://github.com/antitypical/Result))

Example to submit a google search
```swift
let url = NSURL(string:"https://www.google.com")!
let value = "Erik The Phantom of Opera"
// visit
var future: Future = Erik.visitFuture(url: url)
// fill input field
future = future.flatMap { document -> Future in
if let input = document.querySelector("input[name='q']") {
input["value"] = value
}
if let form = document.querySelector("form[name=\"f\"]") as? Form {
form.submit()
}
return Erik.currentContentFuture()
}
// finally get final result as success or error
future.onSuccess { document in
// parse result
}
future.onFailure { error in
print("\(error)")
}
```

## Limitation
On iOS 9 and macOS 10.11, you need to ensure you use https://, because iOS 9 and macOS 10.11 do not like apps sending or receiving data insecurely. If this something you want to override, click here to read about [App Transport Security](https://github.com/OAuthSwift/OAuthSwift/wiki/App-Transport-Security).

## Links
- [A list of (almost) all headless web browsers in existence](https://github.com/dhamaniasad/HeadlessBrowsers)
- [Wikipedia Headless browser](https://en.wikipedia.org/wiki/Headless_browser)

## Setup

### Using [cocoapods](http://cocoapods.org/) ##
[CocoaPods](https://cocoapods.org/) is a centralized dependency manager for
Objective-C and Swift. Go [here](https://guides.cocoapods.org/using/index.html)
to learn more.

1. Add the project to your [Podfile](https://guides.cocoapods.org/using/the-podfile.html).

```ruby
use_frameworks!

pod 'Erik'
// or specific target
target :test do
pod 'Erik'
end
```

2. Run `pod install` and open the `.xcworkspace` file to launch Xcode.

#### Optional Future
Add `pod 'Erik/Future'` to your `Podfile` and run `pod install`.

## Using carthage ##
[Carthage](https://github.com/Carthage/Carthage) is a decentralized dependency manager for Objective-C and Swift.

1. Add the project to your [Cartfile](https://github.com/Carthage/Carthage/blob/master/Documentation/Artifacts.md#cartfile).

```
github "phimage/Erik"
```

## Roadmap

- [ ] (WIP) WKWebView screenshot (webkit view privates api?)

## Why Erik?

A well known headless browser is named [PhantomJS](http://phantomjs.org/) and a very well known browser is [Opera](http://www.opera.com).

As a tribute I use [Erik](https://en.wikipedia.org/wiki/Erik_(The_Phantom_of_the_Opera)), firstname of the title character from Gaston Leroux's novel *Le Fantôme de l'Opéra* best known to English speakers as [The Phantom of Opera](https://en.wikipedia.org/wiki/The_Phantom_of_the_Opera). 

My name is also Erik. So egotistical to call a project using its firstname isn't it.

My only justification is that I was playing Metal Gear Solid *V* and the creator Hideo Kojima name appears over 100 times in the game. Coincidentally the full name of the game is Metal Gear Solid *V* : The **Phantom** Pain.

## License
The MIT License. See the LICENSE file for more information.