simulacrum 0.3.0 → 0.3.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +74 -56
- data/examples/basic/spec/ui/button_spec.rb +1 -0
- data/lib/simulacrum/cli/parser.rb +2 -50
- data/lib/simulacrum/version.rb +1 -1
- data/simulacrum.gemspec +1 -1
- data/spec/lib/simulacrum/cli/parser_spec.rb +0 -58
- metadata +4 -4
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA1:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 592bbfaa75d268d66b5578382761a253f2d57e86
|
|
4
|
+
data.tar.gz: 7cf962e9ca94a866cbc58ad285b001485b53e194
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: fa86c43103ba1441ebe875ee03d4b01f0b361695f4e3a51c6b1ce560e5fa8f86a32533716eeb29504febaa4e318e5b935bdfa11fc254fba8f852b74e8b973d8c
|
|
7
|
+
data.tar.gz: 3fc708310ac58f684540e712247278f44579502586af90f111bf754f4d4e84cc0eb9bcbfa68a174c9f5cf845191e81ff2f859d42b548a7a712d9fc037c01d914
|
data/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
|
|
1
|
+
# Simulacrum
|
|
2
2
|
|
|
3
3
|
[][travis]
|
|
4
4
|
[][codeclimate]
|
|
@@ -6,99 +6,117 @@
|
|
|
6
6
|
[][gemnasium]
|
|
7
7
|
[][gem_version]
|
|
8
8
|
|
|
9
|
-
**Simulacrum is a UI regression testing tool. It helps you write unit-like tests for
|
|
10
|
-
user-interface components in web applications.**
|
|
9
|
+
**Simulacrum is a UI regression testing tool. It helps you write unit-like tests for user-interface components in web applications.**
|
|
11
10
|
|
|
12
|
-
|
|
11
|
+
Simulacrum allows you to write RSpec style specs that when run will compare screenshots of components of your UI to their last “Known Good State”, and tell you if they’ve changed.
|
|
13
12
|
|
|
14
|
-
|
|
13
|
+
Simulacrum is built around common tools in the Ruby development world, such as [RSpec], [Capybara] & [Selenium Webdriver].
|
|
15
14
|
|
|
16
|
-
|
|
17
|
-
| ---------------- |:------------------------------------------------------------------------------------------- |:------:|
|
|
18
|
-
| **Browserstack** | [plasticine/simulacrum-browserstack](https://github.com/plasticine/simulacrum-browserstack) | WIP 🚧 |
|
|
19
|
-
| **Saucelabs** | [plasticine/simulacrum-saucelabs](https://github.com/plasticine/simulacrum-saucelabs) | WIP 🚧 |
|
|
15
|
+
**🚧 This project is still a Work In Progress™, hopefully it can still be useful for you as I work on making it better and more robust.**
|
|
20
16
|
|
|
21
|
-
|
|
17
|
+
Feedback and PRs accepted and appreciated — see [Development](#Development) below for how to get up and running.
|
|
22
18
|
|
|
23
|
-
|
|
24
|
-
- Know when a component is visually altered
|
|
25
|
-
- Integrate with
|
|
26
|
-
- Test component behaviour (JS) that manipulates visual appearance
|
|
19
|
+
## What problem is this solving?
|
|
27
20
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
### UI Regression Testing
|
|
21
|
+
Traditional UI testing is usually feature and functionality driven, and while this is awesome it is also only really testing half of the actual UI.
|
|
31
22
|
|
|
32
|
-
|
|
23
|
+
Relying solely on functional tests to verify your UI neglects the visual aspect, meaning that a passing functional test can conceal a visually broken piece UI from a user point-of-view (be it from broken CSS or HTML).
|
|
33
24
|
|
|
34
|
-
|
|
25
|
+
At the end of the day if it looks broken it is broken, even if it might still “work”. Frontend tools (particularly CSS, of course) are very brittle and by their nature make it very easy to accidentally break the look of your website.
|
|
35
26
|
|
|
36
|
-
|
|
27
|
+
There is a short slidedeck discussing some of the details and rationale for the project over on [Speakerdeck](https://speakerdeck.com/justinmorris/ui-regression-testing-for-fun-and-profit)
|
|
37
28
|
|
|
38
|
-
|
|
39
|
-
- testing components
|
|
29
|
+
### Simulacrum aims to help you;
|
|
40
30
|
|
|
41
|
-
|
|
31
|
+
- test your UI components visually, and know when they change
|
|
32
|
+
- write easy to read specs that don’t require any real special configuration to work
|
|
33
|
+
- test your UI and multiple screen sizes (mediaqueries)
|
|
34
|
+
- test component behaviour (Javascript) that manipulates visual appearance
|
|
42
35
|
|
|
43
36
|
## Setup
|
|
44
37
|
Simulacrum requires Ruby 1.9.3 or later. To install, add this line to your Gemfile and run `bundle install`:
|
|
45
38
|
|
|
46
|
-
|
|
39
|
+
The next step is to create a `simulacrum_helper.rb` helper file that will help you define any defaults for your tests;
|
|
47
40
|
|
|
48
41
|
```ruby
|
|
49
|
-
|
|
42
|
+
require 'simulacrum'
|
|
43
|
+
|
|
44
|
+
Simulacrum.configure do |config|
|
|
45
|
+
config.component.delta_threshold = 0 # 0% change allowed
|
|
46
|
+
config.component.capture_selector = '.MyComponent' # CSS selector to crop images around
|
|
47
|
+
end
|
|
50
48
|
```
|
|
51
49
|
|
|
52
|
-
|
|
50
|
+
Simulacrum expects your specs to be under `spec/ui/` and be named `*_spec.rb`.
|
|
53
51
|
|
|
54
|
-
|
|
55
|
-
require 'simulacrum'
|
|
56
|
-
```
|
|
52
|
+
## Writing Specs
|
|
57
53
|
|
|
58
|
-
|
|
54
|
+
The simplest Simulacrum spec would look something like this;
|
|
59
55
|
|
|
60
56
|
```ruby
|
|
61
|
-
|
|
62
|
-
|
|
57
|
+
# spec/ui/my_component_spec.rb
|
|
58
|
+
|
|
59
|
+
require 'simulacrum_helper'
|
|
63
60
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
61
|
+
describe 'MyComponent' do
|
|
62
|
+
component :mycomponent do |options|
|
|
63
|
+
options.url = '/link/to/styleguide/example/of/MyComponent.html'
|
|
67
64
|
end
|
|
65
|
+
|
|
66
|
+
it { is_expected.to look_the_same }
|
|
68
67
|
end
|
|
69
68
|
```
|
|
70
69
|
|
|
71
|
-
##
|
|
70
|
+
## Running Specs
|
|
71
|
+
|
|
72
|
+
Simulacrum provides a CLI tool to help you run your tests. It implements the same file/directory execution options as RSpec itself, so running a subset of your specs is possible (see below). For a full list of CLI flags run `simulacrum --help`.
|
|
72
73
|
|
|
74
|
+
##### CLI Usage
|
|
73
75
|
```shell
|
|
74
|
-
simulacrum
|
|
76
|
+
$ simulacrum # Run all specs
|
|
77
|
+
$ simulacrum spec/ui/panels # Run all specs in a directory
|
|
78
|
+
$ simulacrum spec/ui/my_button_spec.rb # Run a specific spec
|
|
75
79
|
```
|
|
76
80
|
|
|
81
|
+
### Examples
|
|
82
|
+
|
|
83
|
+
There are some examples of how Simulacrum can be used in [examples](./tree/master/examples).
|
|
84
|
+
|
|
85
|
+
### Remote Selenium & Cross-device testing
|
|
77
86
|
|
|
87
|
+
Support for 3rd party Selenium Webdriver services (such as [Browserstack], and [Saucelabs]) is provided via additional collaborating gems.
|
|
78
88
|
|
|
89
|
+
| | | Status |
|
|
90
|
+
| ---------------- |:------------------------------------ |:------:|
|
|
91
|
+
| **Browserstack** | [plasticine/simulacrum-browserstack] | WIP 🚧 |
|
|
92
|
+
| **Saucelabs** | [plasticine/simulacrum-saucelabs] | WIP 🚧 |
|
|
79
93
|
|
|
80
|
-
|
|
94
|
+
## Development
|
|
81
95
|
|
|
82
|
-
|
|
83
|
-
- `configure_browser`
|
|
84
|
-
- `look_the_same` -->
|
|
96
|
+
The test suite can be run using `./script/spec`.
|
|
85
97
|
|
|
86
98
|
***
|
|
87
99
|
|
|
88
100
|
#### Inspiration / Similar tools
|
|
89
101
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
[
|
|
95
|
-
[
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
[
|
|
99
|
-
[
|
|
100
|
-
[
|
|
101
|
-
[
|
|
102
|
-
[
|
|
103
|
-
[
|
|
104
|
-
[
|
|
102
|
+
Simulacrum appraoches the idea of UI regression testing by way of screenshots. There are other techniques that could be used to accomplish the same outcome (such as inspecting CSS directly), a good overview of the various techniques is available at [csste.st](http://csste.st/techniques/).
|
|
103
|
+
|
|
104
|
+
Some of the tools that Simulacrum is most similar to, and takes inspiration from:
|
|
105
|
+
|
|
106
|
+
- **[Huxley]** `facebook/huxley`
|
|
107
|
+
- **[Needle]** `bfirsh/needle`
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
[plasticine/simulacrum-browserstack]: https://github.com/plasticine/simulacrum-browserstack
|
|
111
|
+
[plasticine/simulacrum-saucelabs]: https://github.com/plasticine/simulacrum-saucelabs
|
|
112
|
+
[Needle]: https://github.com/bfirsh/needle
|
|
113
|
+
[Huxley]: https://github.com/facebook/huxley
|
|
114
|
+
[Browserstack]: http://www.browserstack.com
|
|
115
|
+
[Saucelabs]: https://saucelabs.com
|
|
116
|
+
[RSpec]: http://rspec.info
|
|
117
|
+
[Capybara]: https://github.com/jnicklas/capybara
|
|
118
|
+
[Selenium Webdriver]: http://docs.seleniumhq.org/projects/webdriver/
|
|
119
|
+
[codeclimate]: https://codeclimate.com/github/plasticine/simulacrum
|
|
120
|
+
[travis]: https://travis-ci.org/plasticine/simulacrum
|
|
121
|
+
[gemnasium]: https://gemnasium.com/plasticine/simulacrum
|
|
122
|
+
[gem_version]: http://badge.fury.io/rb/simulacrum
|
|
@@ -23,7 +23,6 @@ module Simulacrum
|
|
|
23
23
|
@stdout = stdout
|
|
24
24
|
|
|
25
25
|
add_banner
|
|
26
|
-
add_runner_options
|
|
27
26
|
add_format_options
|
|
28
27
|
add_separator
|
|
29
28
|
add_version
|
|
@@ -46,23 +45,7 @@ module Simulacrum
|
|
|
46
45
|
private
|
|
47
46
|
|
|
48
47
|
def default_options
|
|
49
|
-
|
|
50
|
-
apikey: ENV['SIMULACRUM_APIKEY'])
|
|
51
|
-
end
|
|
52
|
-
|
|
53
|
-
def read_options_from_file
|
|
54
|
-
if Simulacrum.config_file?
|
|
55
|
-
filter_file_options(Simulacrum.config_file)
|
|
56
|
-
else
|
|
57
|
-
{}
|
|
58
|
-
end
|
|
59
|
-
end
|
|
60
|
-
|
|
61
|
-
def filter_file_options(file_options)
|
|
62
|
-
file_options.tap do |hash|
|
|
63
|
-
hash.delete('username')
|
|
64
|
-
hash.delete('apikey')
|
|
65
|
-
end
|
|
48
|
+
{}
|
|
66
49
|
end
|
|
67
50
|
|
|
68
51
|
def add_banner
|
|
@@ -82,44 +65,13 @@ module Simulacrum
|
|
|
82
65
|
end
|
|
83
66
|
|
|
84
67
|
def add_help
|
|
85
|
-
parser.on_tail('-h', '--help', '
|
|
68
|
+
parser.on_tail('-h', '--help', 'You\'re looking at it!') do
|
|
86
69
|
stdout.puts parser
|
|
87
70
|
fail OptionsHandled
|
|
88
71
|
end
|
|
89
72
|
end
|
|
90
73
|
|
|
91
|
-
def add_runner_options
|
|
92
|
-
parser.on('--runner [RUNNER]',
|
|
93
|
-
[:browserstack],
|
|
94
|
-
'Runner to use for executing specs (browserstack).') do |runner|
|
|
95
|
-
options['runner'] = runner
|
|
96
|
-
end
|
|
97
|
-
|
|
98
|
-
parser.on('--username [USERNAME]',
|
|
99
|
-
'Username for authenticating when using the Browserstack runner.') do |username|
|
|
100
|
-
options['username'] = username
|
|
101
|
-
end
|
|
102
|
-
|
|
103
|
-
parser.on('--apikey [APIKEY]',
|
|
104
|
-
'API key for authenticating when using the Browserstack runner.') do |apikey|
|
|
105
|
-
options['apikey'] = apikey
|
|
106
|
-
end
|
|
107
|
-
|
|
108
|
-
parser.on('--max-processes [N]',
|
|
109
|
-
Integer,
|
|
110
|
-
'Number of parallel proceses the runner should use.') do |max_processes|
|
|
111
|
-
options['max_processes'] = max_processes.to_i
|
|
112
|
-
end
|
|
113
|
-
|
|
114
|
-
parser.on('--browser [BROWSER]',
|
|
115
|
-
'Browser configuration to use') do |browser|
|
|
116
|
-
options['browser'] = browser.to_sym
|
|
117
|
-
end
|
|
118
|
-
end
|
|
119
|
-
|
|
120
74
|
def add_format_options
|
|
121
|
-
add_separator
|
|
122
|
-
|
|
123
75
|
parser.on('-c',
|
|
124
76
|
'--[no-]color',
|
|
125
77
|
'--[no-]colour',
|
data/lib/simulacrum/version.rb
CHANGED
data/simulacrum.gemspec
CHANGED
|
@@ -31,7 +31,7 @@ Gem::Specification.new do |gem|
|
|
|
31
31
|
gem.add_dependency 'capybara', ['~> 2.4.1']
|
|
32
32
|
gem.add_dependency 'rmagick', '~> 2.13.2'
|
|
33
33
|
gem.add_dependency 'rspec', ['>= 2.14.1']
|
|
34
|
-
gem.add_dependency 'selenium-webdriver', ['~> 2.
|
|
34
|
+
gem.add_dependency 'selenium-webdriver', ['~> 2.43.0']
|
|
35
35
|
|
|
36
36
|
gem.add_development_dependency 'appraisal'
|
|
37
37
|
gem.add_development_dependency 'aruba'
|
|
@@ -52,62 +52,4 @@ describe Simulacrum::CLI::Parser do
|
|
|
52
52
|
it { expect(subject.result.verbose).to eq(true) }
|
|
53
53
|
end
|
|
54
54
|
end
|
|
55
|
-
|
|
56
|
-
describe '--runner' do
|
|
57
|
-
it { expect(subject.result.runner).to be_nil }
|
|
58
|
-
|
|
59
|
-
context 'when the option is set' do
|
|
60
|
-
let(:option) { '--runner browserstack' }
|
|
61
|
-
|
|
62
|
-
it { expect(subject.result.runner).to eq(:browserstack) }
|
|
63
|
-
end
|
|
64
|
-
|
|
65
|
-
context 'when the option is set to an invalid value' do
|
|
66
|
-
let(:option) { '--runner dropbear' }
|
|
67
|
-
|
|
68
|
-
it 'throws an InvalidArgument exception' do
|
|
69
|
-
expect { subject.result.runner }.to raise_error(OptionParser::InvalidArgument)
|
|
70
|
-
end
|
|
71
|
-
end
|
|
72
|
-
end
|
|
73
|
-
|
|
74
|
-
describe '--username' do
|
|
75
|
-
it { expect(subject.result.username).to be_nil }
|
|
76
|
-
|
|
77
|
-
context 'when the option is set' do
|
|
78
|
-
let(:option) { '--username justin' }
|
|
79
|
-
|
|
80
|
-
it { expect(subject.result.username).to eq('justin') }
|
|
81
|
-
end
|
|
82
|
-
end
|
|
83
|
-
|
|
84
|
-
describe '--apikey' do
|
|
85
|
-
it { expect(subject.result.apikey).to be_nil }
|
|
86
|
-
|
|
87
|
-
context 'when the option is set' do
|
|
88
|
-
let(:option) { '--apikey 1234abcd' }
|
|
89
|
-
|
|
90
|
-
it { expect(subject.result.apikey).to eq('1234abcd') }
|
|
91
|
-
end
|
|
92
|
-
end
|
|
93
|
-
|
|
94
|
-
describe '--max-processes' do
|
|
95
|
-
it { expect(subject.result.max_processes).to be_nil }
|
|
96
|
-
|
|
97
|
-
context 'when the option is set' do
|
|
98
|
-
let(:option) { '--max-processes 5' }
|
|
99
|
-
|
|
100
|
-
it { expect(subject.result.max_processes).to eq(5) }
|
|
101
|
-
end
|
|
102
|
-
end
|
|
103
|
-
|
|
104
|
-
describe '--browser' do
|
|
105
|
-
it { expect(subject.result.browser).to be_nil }
|
|
106
|
-
|
|
107
|
-
context 'when the option is set' do
|
|
108
|
-
let(:option) { '--browser firefox' }
|
|
109
|
-
|
|
110
|
-
it { expect(subject.result.browser).to eq(:firefox) }
|
|
111
|
-
end
|
|
112
|
-
end
|
|
113
55
|
end
|
metadata
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: simulacrum
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.3.
|
|
4
|
+
version: 0.3.1
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Justin Morris
|
|
8
8
|
autorequire:
|
|
9
9
|
bindir: exe
|
|
10
10
|
cert_chain: []
|
|
11
|
-
date: 2014-09-
|
|
11
|
+
date: 2014-09-29 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: capybara
|
|
@@ -58,14 +58,14 @@ dependencies:
|
|
|
58
58
|
requirements:
|
|
59
59
|
- - ~>
|
|
60
60
|
- !ruby/object:Gem::Version
|
|
61
|
-
version: 2.
|
|
61
|
+
version: 2.43.0
|
|
62
62
|
type: :runtime
|
|
63
63
|
prerelease: false
|
|
64
64
|
version_requirements: !ruby/object:Gem::Requirement
|
|
65
65
|
requirements:
|
|
66
66
|
- - ~>
|
|
67
67
|
- !ruby/object:Gem::Version
|
|
68
|
-
version: 2.
|
|
68
|
+
version: 2.43.0
|
|
69
69
|
- !ruby/object:Gem::Dependency
|
|
70
70
|
name: appraisal
|
|
71
71
|
requirement: !ruby/object:Gem::Requirement
|