jekyll-joule 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a4e2101503338f46fba3f5d6350affa42d1e5ef1
-  data.tar.gz: 8e7a846a2fd33971fc698b000f62a2363cc6c486
+  metadata.gz: 3d9106e4d2029a3eff12d283263d222ac4af2ddf
+  data.tar.gz: e71183c5bb01ae0989d99557b0780486addbe1fd
 SHA512:
-  metadata.gz: '02328add785b1185da1b1380a1b9f0891626fbce6b0b8b540142d022645c4624d747cf9759340aa0e5a3fddf3834a3dd596d3a0a12dc78828ee1ddeaa786a1d6'
-  data.tar.gz: 9b2eb2342c9bf9b6b715bbbd5e784ce32c7c35dcc059885b42e12e3b5aedde64746ec42d1ccf295790fb6085c2b0066c178499c08558395c5a8cba9cc78cb7dc
+  metadata.gz: 6f6d471da8656f570362d52fc0997910c7410f39dab2e27b41d2ee875028703f07657278024d911bb344fd2b32d286acb4e5e7c852d1a26a67fe8b43aac3034f
+  data.tar.gz: 92db87cf50fb452144b5360604e29951709f6f7a663659de4701894e92dd682b33afe56081bfd592c2e648a03825160ccafc84d86c866fdb356d766bcca6bd6c

data/README.md

@@ -24,11 +24,42 @@ gem install jekyll-joule
 ```
 
 
+
+## Basic Usage
+
+Below is an example of how you can write a test with Joule.
+
+```rb
+class ExampleTest < JekyllUnitTest
+  should "render a div containing the Page title" do
+    @joule.render(%Q[
+      ---
+      title: "Yiss"
+      ---
+      <div class="aww">
+        {{ page.title }}
+      </div>
+    ])
+
+    el = @joule.find(".aww")
+
+    assert(el)
+    assert(el.text.include?("Yiss"))
+    assert(el["class"].include?("aww"))
+  end
+end
+```
+
+Check out the full [rendering API documentation](./docs/rendering.md)
+
+
+
 ## Documentation
 
 **[View the docs](https://github.com/helpscout/jekyll-joule/blob/master/docs/introduction.md)** to get started with Joule!
 
 
+
 ## Examples
 
 **[View the example](https://github.com/helpscout/jekyll-joule/tree/master/examples)** Jekyll setup + Joule test files.

data/docs/api/find.md

@@ -0,0 +1,66 @@
+# .find()
+
+#### .find(selector)
+
+| Argument | Type | Description |
+| --- | --- | --- |
+| selector | string | HTML selectors to find within your rendered Joule instance. |
+
+
+#### Returns
+
+| Type | Description |
+| --- | --- |
+| instance | A [Nokogiri](https://github.com/sparklemotion/nokogiri) element instance. |
+
+
+## Usage
+
+```rb
+html = %Q[
+  <div class="pikachu">
+    {% include card/header/thunderbolt.html %}
+    <blockquote class="quote">Pika-pi</blockquote>
+    {% include card/footer.html %}
+  </div>
+]
+
+@joule.render(html)
+
+el = @joule.find("blockquote")
+```
+
+In the above example, the variable `el` would be a Nokogiri element for:
+
+```html
+<blockquote class="quote">Pika-pi</blockquote>
+```
+
+That means that you'll be able to check the properties of this element by using methods like:
+
+```ruby
+el.text       # Pika-pi
+el["class"]   # quote
+```
+
+### Chaining
+
+Joule has enhanced Nokogiri's Element class by allowing you to find elements within elements.
+
+In the example below, we're able to find the inner `.pika` selector within the outer `.pikachu` selector.
+```rb
+html = %Q[
+  <div class="pikachu">
+    <div class="pika">
+      <blockquote class="quote">
+        Pika-pi
+      </blockquote>
+    </div>
+  </div>
+]
+
+@joule.render(html)
+
+outer = @joule.find(".pikachu")
+inner = outer.find(".pika")
+```

data/docs/api/find_all.md

@@ -0,0 +1,51 @@
+# .find_all()
+
+#### .find_all(selector)
+
+| Argument | Type | Description |
+| --- | --- | --- |
+| selector | string | HTML selectors to find within your rendered Joule instance. |
+
+
+#### Returns
+
+| Type | Description |
+| --- | --- |
+| array | An array of [Nokogiri](https://github.com/sparklemotion/nokogiri) element instances. |
+
+
+## Usage
+
+```rb
+html = %Q[
+  <div class="pikachu">
+    <div class="spark">One</div>
+    <div class="spark">Two</div>
+    <div class="spark">Three</div>
+    <div class="spark">Fourteen</div>
+  </div>
+]
+
+@joule.render(html)
+
+els = @joule.find_all(".spark")
+```
+
+In the above example, the variable `els` would be an Array of 4 Nokogiri elements for:
+
+```html
+<div class="spark">...</div>
+```
+
+To check the properties of an individual element from your array, you'll need to select a single element.
+
+Example:
+```ruby
+els = @joule.find_all(".spark")
+
+el = els.first
+# or
+el = els.last
+# or
+el = els[0]
+```

data/docs/api/render.md

@@ -0,0 +1,52 @@
+# .render()
+
+#### .render(content)
+
+| Argument | Type | Description |
+| --- | --- | --- |
+| content | string | The HTML to be parsed and rendered by Jekyll. |
+
+
+#### Returns
+
+| Type | Description |
+| --- | --- |
+| instance | Joule Site instance. |
+
+
+
+## Usage
+
+The easiest way to pass an HTML string into `@Joule` is to use Ruby's [`%Q string interpolator](https://en.wikibooks.org/wiki/Ruby_Programming/Syntax/Literals).
+
+Joule's render method accepts anything you'd expect Jekyll to be able to render. That includes HTML and Liquid tags, blocks, and filters (like `{% include %}`).
+
+```rb
+html = %Q[
+  <div class="pikachu">
+    {% include card/header/thunderbolt.html %}
+    <blockquote>Pika-pi</blockquote>
+    {% include card/footer.html %}
+  </div>
+]
+
+@joule.render(html)
+```
+
+
+### Markdown
+
+Joule's `,render()` method accepts markdown as well!
+
+```rb
+markdown = %Q[
+  # Pikachu
+  {% include card/header/thunderbolt.html %}
+
+  > Pika-pi
+
+  {% include card/footer.html %}
+]
+
+@joule.render(markdown)
+```

data/docs/rendering.md

@@ -0,0 +1,38 @@
+# Rendering
+
+Joule makes it super easy to write and render HTML for Jekyll.
+
+This allows you to inline small chunks of HTML for your unit tests. This inline technique allows you to write many tests really quickly. It also makes it really clear what you are testing.
+
+
+
+## API
+
+Joule comes with a handful of methods to help you render and find HTML selectors for testing:
+
+* [.render()](./api/render.md)
+* [.find()](./api/find.md)
+* [.find_all()](./api/find_all.md)
+
+
+
+## Usage
+
+In the following example, we're going to be rendering some HTML markup along with a couple of Jekyll `{% include %}` tags. For our test, we're checking to see if the `card/header/thunderbolt.html` include does what we expect it to do.
+
+```rb
+should "render include header markup" do
+  html = %Q[
+    <div class="pikachu">
+      {% include card/header/thunderbolt.html %}
+      <blockquote class="quote">Pika-pi</blockquote>
+      {% include card/footer.html %}
+    </div>
+  ]
+  @joule.render(html)
+  el = @joule.find(".card-header")
+
+  assert(el.text.include?("Header Yay!"))
+  assert(el["class"].include?("thunderbolt"))
+end
+```

data/docs/setup.md

@@ -4,7 +4,7 @@ The are a couple of things you need to do to get started with writing Jekyll tes
 
 The following steps are based on Jekyll's own [test setup](https://github.com/jekyll/jekyll/tree/master/test). However, they've been simplified to make it easier to follow 😘.
 
-> ## TLDR
+> ## TL;DR
 > You can find all of the setup code in our [examples](https://github.com/helpscout/jekyll-joule/tree/master/examples).
 
 ## Add test dependencies
@@ -108,4 +108,4 @@ To confirm, run the following command:
 
 As long as you don't see a bunch of errors in your Terminal (😱), then you're good!
 
-Next, let's start **[writing some tests!](./writing-tests.md)**!
+Next, let's start **[writing some tests](./writing-tests.md)**!

data/docs/writing-tests.md

@@ -0,0 +1,87 @@
+# Writing Tests
+
+Now that we've [set up](./setup.md) our Jekyll project for testing, let's add our first test file.
+
+> ## TL;DR
+> You can find an example test in our [examples](https://github.com/helpscout/jekyll-joule/tree/master/examples/test).
+
+## Add your test file
+
+In your `test/` directory, add a new `.rb` with a name that describes what you're testing. Don't forget to start the file name with `test_`!
+
+```shell
+my-jekyll/
+├── ...
+├── test/
+│   ├── helper.rb
+│   └── test_yiss.rb
+├── Gemfile
+└── Rakefile
+```
+
+
+## Write your test
+
+Copy/paste the following into your new `test_yiss.rb` file. Feel free to remove all of the Ruby comments!
+
+```ruby
+# Remember our helper.rb setup file? We'll be needing that.
+require "helper"
+
+# Name the class of your test whatever it is you'd like!
+# Ideally, you'd want something that describes what you're testing.
+class AwwYissTest < JekyllUnitTest
+  # should describes what it is you're testing
+  should "render a div" do
+    # 1. Write your markup
+    html = %Q[
+      <div class="aww">
+        Yiss
+      </div>
+    ]
+
+    # 2. Pass it into Joule for rendering
+    @joule.render(html)
+
+    # 3. Find your HTML element(s)
+    el = @joule.find(".aww")
+
+    # 4. Write tests
+    assert(el)
+    assert(el.text.include?("Yiss"))
+    assert(el["class"].include?("aww"))
+  end
+end
+```
+
+For this super simple test, all we're doing is checking if the HTML provided within the `%Q[]` tag has the text and class we expect it to have when rendered.
+
+
+## Run your test
+
+To actually run your test, run the following command (you're probably going to be doing this a lot):
+
+`bundle exec rake test`
+
+If all goes well, you should see something like this in your Terminal:
+
+```
+Finished in 0.05835s
+1 tests, 3 assertions, 0 failures, 0 errors, 0 skips
+```
+
+And that's it! You've written your first Jekyll unit test with Minitest and Joule! 🚀
+
+
+![Aww yiss](https://media.giphy.com/media/S4P8Z5fiLRpOU/giphy.gif)<br>
+_Aww yiss!_
+
+
+Joule supports Jekyll plugins, `{% include %}`, Liquid filters, and all the fun things you'd expect from your Jekyll code.
+
+Good luck and have fun testing! ✌️😎
+
+
+## Wanna learn more?
+
+To learn more about how you can use Joule, check out our **[rendering docs](./rendering.md)**.

data/examples/test/source/index.md

@@ -0,0 +1,5 @@
+---
+title: "Site"
+---
+
+Add test pages/posts in this source directory :)

data/examples/test/test_example.rb

@@ -13,11 +13,11 @@ class ExampleTest < JekyllUnitTest
     @joule.render(html)
 
     # 3. Find your HTML element(s)
-    el = @joule.find(".hello")
+    el = @joule.find(".aww")
 
     # 4. Write tests
     assert(el)
-    assert(el.text.include?("Hello"))
-    assert(el["class"].include?("hello"))
+    assert(el.text.include?("Yiss"))
+    assert(el["class"].include?("aww"))
   end
 end

data/lib/jekyll/joule/site.rb

@@ -36,9 +36,8 @@ module Jekyll
       def render(content)
         page = Jekyll::Joule::Page.new(@site, @site.source, "/", @test_page_name)
         page.reparse(content)
-        page.content = %Q[<div id="#{@fixture_id}">#{page.content}</div>]
         @data = generate(page)
-        @html = Nokogiri::HTML(@data["content"]).css(%Q[##{@fixture_id}])[0]
+        @html = Nokogiri::HTML(@data.content)
 
         return self
       end

data/lib/jekyll/joule/version.rb

@@ -1,5 +1,5 @@
 module Jekyll
   module Joule
-    VERSION = "0.0.3"
+    VERSION = "0.0.4"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-joule
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - ItsJonQ
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-06-04 00:00:00.000000000 Z
+date: 2017-06-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -191,12 +191,17 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/api/find.md
+- docs/api/find_all.md
+- docs/api/render.md
 - docs/introduction.md
+- docs/rendering.md
 - docs/setup.md
+- docs/writing-tests.md
 - examples/Gemfile
 - examples/Rakefile
 - examples/test/helper.rb
-- examples/test/source/joule.md
+- examples/test/source/index.md
 - examples/test/test_example.rb
 - jekyll-joule.gemspec
 - lib/jekyll-joule.rb

data/examples/test/source/joule.md

@@ -1,3 +0,0 @@
----
-title: "Joule"
----