README.md in simulacrum-0.3.0 vs README.md in simulacrum-0.3.1
- old
+ new
@@ -1,104 +1,122 @@
-## Simulacrum
+# Simulacrum
[][travis]
[][codeclimate]
[][codeclimate]
[][gemnasium]
[][gem_version]
-**Simulacrum is a UI regression testing tool. It helps you write unit-like tests for
-user-interface components in web applications.**
+**Simulacrum is a UI regression testing tool. It helps you write unit-like tests for user-interface components in web applications.**
-It is built around common tools such as [RSpec], [Capybara] & [Selenium Webdriver].
+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.
-Support for 3rd party Selenium Webdriver services (such as [Browserstack], and [Saucelabs]) is provided via additional collaborating gems;
+Simulacrum is built around common tools in the Ruby development world, such as [RSpec], [Capybara] & [Selenium Webdriver].
-| | | Status |
-| ---------------- |:------------------------------------------------------------------------------------------- |:------:|
-| **Browserstack** | [plasticine/simulacrum-browserstack](https://github.com/plasticine/simulacrum-browserstack) | WIP 🚧 |
-| **Saucelabs** | [plasticine/simulacrum-saucelabs](https://github.com/plasticine/simulacrum-saucelabs) | WIP 🚧 |
+**🚧 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.**
-#### Does this sound like something you might be interested in?
+Feedback and PRs accepted and appreciated — see [Development](#Development) below for how to get up and running.
-- Test your UI components visually
-- Know when a component is visually altered
-- Integrate with
-- Test component behaviour (JS) that manipulates visual appearance
+## What problem is this solving?
-***
+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.
-### UI Regression Testing
+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).
-Explain the use-case better.
+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.
-### Opinions
+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)
-Simulacrum is a little bit opinionated about a few things;
+### Simulacrum aims to help you;
-- selenium webdriver (browserstack)
-- testing components
+- test your UI components visually, and know when they change
+- write easy to read specs that don’t require any real special configuration to work
+- test your UI and multiple screen sizes (mediaqueries)
+- test component behaviour (Javascript) that manipulates visual appearance
-It would be good to explain these opinions, the reason for them and why they are good.
-
## Setup
Simulacrum requires Ruby 1.9.3 or later. To install, add this line to your Gemfile and run `bundle install`:
-Create a spec helper file for simulacrum — `simulacrum_helper.rb` — and throw this junk in it:
+The next step is to create a `simulacrum_helper.rb` helper file that will help you define any defaults for your tests;
```ruby
-gem 'simulacrum'
+require 'simulacrum'
+
+Simulacrum.configure do |config|
+ config.component.delta_threshold = 0 # 0% change allowed
+ config.component.capture_selector = '.MyComponent' # CSS selector to crop images around
+end
```
-The next step is to create a `simulacrum_helper.rb` helper file, and then require Simulacrum there:
+Simulacrum expects your specs to be under `spec/ui/` and be named `*_spec.rb`.
-```ruby
-require 'simulacrum'
-```
+## Writing Specs
-Then you can configure Simulacrum within Rspec:
+The simplest Simulacrum spec would look something like this;
```ruby
-RSpec.configure do |config|
- include Simulacrum
+# spec/ui/my_component_spec.rb
- Simulacrum.configure do |config|
- config.defaults.acceptable_delta = 1 # up to 1% percentage change allowed
- config.defaults.capture_selector = '.components__examples' # CSS selector to crop reference image to
+require 'simulacrum_helper'
+
+describe 'MyComponent' do
+ component :mycomponent do |options|
+ options.url = '/link/to/styleguide/example/of/MyComponent.html'
end
+
+ it { is_expected.to look_the_same }
end
```
-## Usage
+## Running Specs
+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`.
+
+##### CLI Usage
```shell
-simulacrum --help
+$ simulacrum # Run all specs
+$ simulacrum spec/ui/panels # Run all specs in a directory
+$ simulacrum spec/ui/my_button_spec.rb # Run a specific spec
```
+### Examples
+There are some examples of how Simulacrum can be used in [examples](./tree/master/examples).
+### Remote Selenium & Cross-device testing
-<!-- Simulacrum provides a small DSL for configuring and managing UI tests from within Rspec. Basically it boils down to these three methods;
+Support for 3rd party Selenium Webdriver services (such as [Browserstack], and [Saucelabs]) is provided via additional collaborating gems.
-- `component`
-- `configure_browser`
-- `look_the_same` -->
+| | | Status |
+| ---------------- |:------------------------------------ |:------:|
+| **Browserstack** | [plasticine/simulacrum-browserstack] | WIP 🚧 |
+| **Saucelabs** | [plasticine/simulacrum-saucelabs] | WIP 🚧 |
+## Development
+
+The test suite can be run using `./script/spec`.
+
***
#### Inspiration / Similar tools
-- Huxley
-- Green Onion
+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/).
+Some of the tools that Simulacrum is most similar to, and takes inspiration from:
-[huxley]: https://github.com/facebook/huxley
-[green_onion]: http://intridea.github.io/green_onion
-[Browserstack]: http://www.browserstack.com
-[Saucelabs]: https://saucelabs.com
-[RSpec]: http://rspec.info
-[Capybara]: https://github.com/jnicklas/capybara
-[Selenium Webdriver]: http://docs.seleniumhq.org/projects/webdriver/
-[codeclimate]: https://codeclimate.com/github/plasticine/simulacrum
-[travis]: https://travis-ci.org/plasticine/simulacrum
-[gemnasium]: https://gemnasium.com/plasticine/simulacrum
-[gem_version]: http://badge.fury.io/rb/simulacrum
+- **[Huxley]** `facebook/huxley`
+- **[Needle]** `bfirsh/needle`
+
+
+[plasticine/simulacrum-browserstack]: https://github.com/plasticine/simulacrum-browserstack
+[plasticine/simulacrum-saucelabs]: https://github.com/plasticine/simulacrum-saucelabs
+[Needle]: https://github.com/bfirsh/needle
+[Huxley]: https://github.com/facebook/huxley
+[Browserstack]: http://www.browserstack.com
+[Saucelabs]: https://saucelabs.com
+[RSpec]: http://rspec.info
+[Capybara]: https://github.com/jnicklas/capybara
+[Selenium Webdriver]: http://docs.seleniumhq.org/projects/webdriver/
+[codeclimate]: https://codeclimate.com/github/plasticine/simulacrum
+[travis]: https://travis-ci.org/plasticine/simulacrum
+[gemnasium]: https://gemnasium.com/plasticine/simulacrum
+[gem_version]: http://badge.fury.io/rb/simulacrum