meta_events 1.0.1

data/spec/meta_events/controller_methods_and_helpers_spec.rb

@@ -0,0 +1,253 @@
+require 'meta_events'
+
+describe MetaEvents::ControllerMethods do
+  before :each do
+    @definition_set = MetaEvents::Definition::DefinitionSet.new(:global_events_prefix => "xy") do
+      version 1, '2014-01-31' do
+        category :foo do
+          event :bar, '2014-01-31', 'this is bar'
+          event :baz, '2014-01-31', 'this is baz'
+        end
+      end
+    end
+    @tracker = ::MetaEvents::Tracker.new("abc123", nil, :definitions => @definition_set, :implicit_properties => { :imp1 => 'imp1val1' })
+
+    @klass = Class.new do
+      class << self
+        def helper_method(*args)
+          @_helper_methods ||= [ ]
+          @_helper_methods += args
+        end
+
+        def helper_methods_registered
+          @_helper_methods
+        end
+      end
+
+      def link_to(*args, &block)
+        @_link_to_calls ||= [ ]
+        @_link_to_calls << args + [ block ]
+        "link_to_call_#{@_link_to_calls.length}"
+      end
+
+      def link_to_calls
+        @_link_to_calls
+      end
+
+      attr_accessor :meta_events_tracker
+
+      include MetaEvents::ControllerMethods
+      include MetaEvents::Helpers
+    end
+
+    @obj = @klass.new
+    @obj.meta_events_tracker = @tracker
+  end
+
+  it "should register the proper helper methods" do
+    expect(@klass.helper_methods_registered.map(&:to_s).sort).to eq(
+      [ :meta_events_define_frontend_event, :meta_events_defined_frontend_events, :meta_events_tracker ].map(&:to_s).sort)
+  end
+
+  describe "frontend-event registration" do
+    def expect_defined_event(name, event_name, properties, options = { })
+      expected_distinct_id = options[:distinct_id] || 'abc123'
+      expect(@obj.meta_events_defined_frontend_events[name]).to eq({
+        :distinct_id => expected_distinct_id,
+        :event_name => event_name,
+        :properties => properties
+      })
+
+      js = @obj.meta_events_frontend_events_javascript
+      expect(js).to match(/MetaEvents\.registerFrontendEvent\s*\(\s*["']#{name}["']/i)
+      js =~ /["']#{name}["']\s*,\s*(.*?)\s*\)\s*\;/i
+      matched = $1
+      hash = JSON.parse($1)
+      expect(hash).to eq('distinct_id' => expected_distinct_id, 'event_name' => event_name, 'properties' => properties)
+    end
+
+    it "should work fine if there are no registered events" do
+      expect(@obj.meta_events_defined_frontend_events).to eq({ })
+      expect(@obj.meta_events_frontend_events_javascript).to eq("")
+    end
+
+    it "should not let you register a nonexistent event" do
+      expect { @obj.meta_events_define_frontend_event(:foo, :quux) }.to raise_error(ArgumentError, /quux/i)
+    end
+
+    it "should let you alias the event to anything you want" do
+      @obj.meta_events_define_frontend_event(:foo, :bar, { :aaa => 'bbb' }, :name => 'zyxwvu')
+      expect_defined_event('zyxwvu', 'xy1_foo_bar', { 'imp1' => 'imp1val1', 'aaa' => 'bbb' })
+    end
+
+    it "should let you override the tracker if you want" do
+      ds2 = MetaEvents::Definition::DefinitionSet.new(:global_events_prefix => "ab") do
+        version 2, '2014-01-31' do
+          category :aaa do
+            event :bbb, '2014-01-31', 'this is bar'
+          end
+        end
+      end
+      t2 = ::MetaEvents::Tracker.new("def345", nil, :definitions => ds2, :version => 2)
+
+      @obj.meta_events_define_frontend_event(:aaa, :bbb, { }, :tracker => t2)
+      expect_defined_event('aaa_bbb', 'ab2_aaa_bbb', { }, { :distinct_id => 'def345' })
+    end
+
+    it "should let you overwrite implicit properties and do hash expansion" do
+      @obj.meta_events_define_frontend_event(:foo, :bar, { :imp1 => 'imp1val2', :a => { :b => 'c', :d => 'e' } })
+      expect_defined_event('foo_bar', 'xy1_foo_bar', { 'imp1' => 'imp1val2', 'a_b' => 'c', 'a_d' => 'e' })
+    end
+
+    context "with one simple defined event" do
+      before :each do
+        @obj.meta_events_define_frontend_event(:foo, :bar, { :quux => 123 })
+      end
+
+      it "should output that event (only) in the JavaScript and via meta_events_define_frontend_event" do
+        expect(@obj.meta_events_defined_frontend_events.keys).to eq(%w{foo_bar})
+        expect_defined_event('foo_bar', 'xy1_foo_bar', { 'quux' => 123, 'imp1' => 'imp1val1' })
+      end
+
+      it "should overwrite the event if a new one is registered" do
+        @obj.meta_events_define_frontend_event(:foo, :baz, { :marph => 345 }, :name => 'foo_bar')
+        expect_defined_event('foo_bar', 'xy1_foo_baz', { 'marph' => 345, 'imp1' => 'imp1val1' })
+      end
+    end
+
+    context "with three defined events" do
+      before :each do
+        @obj.meta_events_define_frontend_event(:foo, :bar, { :quux => 123 })
+        @obj.meta_events_define_frontend_event(:foo, :bar, { :quux => 345 }, { :name => :voodoo })
+        @obj.meta_events_define_frontend_event(:foo, :baz, { :marph => 'whatever' })
+      end
+
+      it "should output all the events in the JavaScript and via meta_events_define_frontend_event" do
+        expect(@obj.meta_events_defined_frontend_events.keys.sort).to eq(%w{foo_bar foo_baz voodoo}.sort)
+        expect_defined_event('foo_bar', 'xy1_foo_bar', { 'quux' => 123, 'imp1' => 'imp1val1' })
+        expect_defined_event('voodoo', 'xy1_foo_bar', { 'quux' => 345, 'imp1' => 'imp1val1' })
+        expect_defined_event('foo_baz', 'xy1_foo_baz', { 'marph' => 'whatever', 'imp1' => 'imp1val1' })
+      end
+    end
+  end
+
+  describe "auto-tracking" do
+    def meta4(h)
+      @obj.meta_events_tracking_attributes_for(h, @tracker)
+    end
+
+    it "should return the input attributes unchanged if there is no :meta_event" do
+      input = { :foo => 'bar', :bar => 'baz' }
+      expect(meta4(input)).to be(input)
+    end
+
+    it "should fail if :meta_event is not a Hash" do
+      expect { meta4(:meta_event => 'bonk') }.to raise_error(ArgumentError)
+    end
+
+    it "should fail if :meta_event contains unknown keys" do
+      me = { :category => 'foo', :event => 'bar', :properties => { }, :extra => 'whatever' }
+      expect { meta4(:meta_event => me) }.to raise_error(ArgumentError)
+    end
+
+    it "should fail if there is no :category" do
+      me = { :event => 'bar', :properties => { } }
+      expect { meta4(:meta_event => me) }.to raise_error(ArgumentError)
+    end
+
+    it "should fail if there is no :event" do
+      me = { :category => 'foo', :properties => { } }
+      expect { meta4(:meta_event => me) }.to raise_error(ArgumentError)
+    end
+
+    def expect_meta4(input, classes, event_name, properties, options = { })
+      attrs = meta4(input)
+
+      expected_prefix = options[:prefix] || "mejtp"
+      expect(attrs['class']).to eq(classes)
+
+      expect(attrs["data-#{expected_prefix}_evt"]).to eq(event_name)
+      prps = JSON.parse(attrs["data-#{expected_prefix}_prp"])
+      expect(prps).to eq(properties)
+
+      remaining = attrs.dup
+      remaining.delete("data-#{expected_prefix}_evt")
+      remaining.delete("data-#{expected_prefix}_prp")
+
+      remaining
+    end
+
+    it "should add class, evt, and prp correctly, and remove :meta_event" do
+      me = { :category => 'foo', :event => 'bar', :properties => { :something => 'awesome' } }
+      remaining = expect_meta4({ :meta_event => me }, %w{mejtp_trk}, 'xy1_foo_bar', { 'something' => 'awesome', 'imp1' => 'imp1val1' })
+      expect(remaining['data']).to be_nil
+    end
+
+    it "should combine the class with an existing class string" do
+      me = { :category => 'foo', :event => 'bar', :properties => { :something => 'awesome' } }
+      remaining = expect_meta4({ :meta_event => me, :class => 'bonko baz' }, [ 'bonko baz', 'mejtp_trk' ], 'xy1_foo_bar', { 'something' => 'awesome', 'imp1' => 'imp1val1' })
+      expect(remaining['data']).to be_nil
+    end
+
+    it "should combine the class with an existing class array" do
+      me = { :category => 'foo', :event => 'bar', :properties => { :something => 'awesome' } }
+      remaining = expect_meta4({ :meta_event => me, :class => %w{bonko baz} }, %w{bonko baz mejtp_trk}, 'xy1_foo_bar', { 'something' => 'awesome', 'imp1' => 'imp1val1' })
+      expect(remaining['data']).to be_nil
+    end
+
+    it "should preserve existing attributes" do
+      me = { :category => 'foo', :event => 'bar', :properties => { :something => 'awesome' } }
+      remaining = expect_meta4({ :meta_event => me, :yo => 'there' }, %w{mejtp_trk}, 'xy1_foo_bar', { 'something' => 'awesome', 'imp1' => 'imp1val1' })
+      expect(remaining['data']).to be_nil
+      expect(remaining[:yo]).to eq('there')
+    end
+
+    it "should preserve existing data attributes" do
+      me = { :category => 'foo', :event => 'bar', :properties => { :something => 'awesome' } }
+      remaining = expect_meta4({ :meta_event => me, :data => { :foo => 'bar', :bar => 'baz' } }, %w{mejtp_trk}, 'xy1_foo_bar', { 'something' => 'awesome', 'imp1' => 'imp1val1' })
+      expect(remaining['data']).to eq({ 'foo' => 'bar', 'bar' => 'baz' })
+    end
+
+    it "should preserve existing data attributes that aren't a Hash" do
+      me = { :category => 'foo', :event => 'bar', :properties => { :something => 'awesome' } }
+      remaining = expect_meta4({ :meta_event => me, :data => "whatever", :'data-foo' => 'bar' }, %w{mejtp_trk}, 'xy1_foo_bar', { 'something' => 'awesome', 'imp1' => 'imp1val1' })
+      expect(remaining['data']).to eq('whatever')
+      expect(remaining['data-foo']).to eq('bar')
+    end
+
+    it "should let you change the tracking prefix" do
+      MetaEvents::Helpers.meta_events_javascript_tracking_prefix 'foo'
+      begin
+        me = { :category => 'foo', :event => 'bar', :properties => { :something => 'awesome' } }
+        remaining = expect_meta4({ :meta_event => me }, %w{foo_trk}, 'xy1_foo_bar', { 'something' => 'awesome', 'imp1' => 'imp1val1' }, { :prefix => 'foo' })
+        expect(remaining['data']).to be_nil
+      ensure
+        MetaEvents::Helpers.meta_events_javascript_tracking_prefix 'mejtp'
+      end
+    end
+
+    describe "#meta_events_tracked_link_to" do
+      it "should raise if there is no :meta_event" do
+        expect { @obj.meta_events_tracked_link_to("foobar", "barfoo") }.to raise_error(ArgumentError)
+      end
+
+      it "should call through to #link_to properly for a simple case" do
+        retval = @obj.meta_events_tracked_link_to("foobar", "barfoo", { :meta_event => { :category => :foo, :event => :bar, :properties => { :a => :b }} })
+        expect(retval).to eq("link_to_call_1")
+
+        calls = @obj.link_to_calls
+        expect(calls.length).to eq(1)
+
+        call = calls[0]
+        expect(call.length).to eq(4)
+        expect(call[0]).to eq("foobar")
+        expect(call[1]).to eq("barfoo")
+        expect(call[2].keys.sort).to eq(%w{class data-mejtp_evt data-mejtp_prp}.sort)
+        expect(call[2]['class']).to eq([ 'mejtp_trk' ])
+        expect(call[2]['data-mejtp_evt']).to eq('xy1_foo_bar')
+        prp = JSON.parse(call[2]['data-mejtp_prp'])
+        expect(prp).to eq({ 'imp1' => 'imp1val1', 'a' => 'b' })
+      end
+    end
+  end
+end

data/spec/meta_events/definition/category_spec.rb

@@ -0,0 +1,102 @@
+require "meta_events"
+
+describe ::MetaEvents::Definition::Category do
+  let(:version) do
+    out = double("version")
+    allow(out).to receive(:kind_of?).with(::MetaEvents::Definition::Version).and_return(true)
+    allow(out).to receive(:prefix).with().and_return("vp_")
+    out
+  end
+  let(:klass) { ::MetaEvents::Definition::Category }
+
+  it "should normalize any name passed in" do
+    expect(klass.normalize_name(:foo)).to eq(:foo)
+    expect(klass.normalize_name('  foo ')).to eq(:foo)
+    expect(klass.normalize_name(:FoO)).to eq(:foo)
+    expect(klass.normalize_name('  FoO ')).to eq(:foo)
+
+    expect { klass.normalize_name(nil) }.to raise_error(ArgumentError)
+    expect { klass.normalize_name("") }.to raise_error(ArgumentError)
+  end
+
+  it "should validate its arguments on construction" do
+    expect { klass.new(double("whatever"), :foo) }.to raise_error(ArgumentError)
+    expect { klass.new(version, nil) }.to raise_error(ArgumentError)
+    expect { klass.new(version, :foo, :bar => :baz) }.to raise_error(ArgumentError, /bar/i)
+
+    # Ruby 1.8.x's Time.parse method will accept "foo" for Time.parse and just return Time.now --
+    # which is deeply unfortunate, but there's really no good way around it.
+    unless RUBY_VERSION =~ /^1\.8\./
+      expect { klass.new(version, :foo, :retired_at => "foo") }.to raise_error(ArgumentError)
+    end
+  end
+
+  it "should run its block in its own context" do
+    expect_any_instance_of(klass).to receive(:foobar).once.with(:bonk)
+    klass.new(version, :foo) { foobar(:bonk) }
+  end
+
+  context "with an instance" do
+    let(:instance) { klass.new(version, :foo) }
+    let(:event) do
+      out = double("event")
+      allow(out).to receive(:name).with().and_return(:baz)
+      out
+    end
+
+    it "should allow creating an Event" do
+      blk = lambda { :whatever }
+      expect(::MetaEvents::Definition::Event).to receive(:new).once.with(instance, :quux, :a, :b, :c => :d).and_return(event)
+      instance.event(:quux, :a, :b, :c => :d)
+    end
+
+    it "should return the prefix correctly" do
+      expect(instance.prefix).to eq("vp_foo_")
+    end
+
+    context "with an event" do
+      before :each do
+        expect(::MetaEvents::Definition::Event).to receive(:new).once.with(instance, :quux, :a, :b, :c => :d).and_return(event)
+        instance.event(:quux, :a, :b, :c => :d)
+      end
+
+      it "should not allow creating two Events with the same name" do
+        event_2 = double("event-2")
+        allow(event_2).to receive(:name).with().and_return(:baz)
+        expect(::MetaEvents::Definition::Event).to receive(:new).once.with(instance, :marph, :www).and_return(event_2)
+
+        expect { instance.event(:marph, :www) }.to raise_error(ArgumentError, /baz/)
+      end
+
+      it "should allow retrieving the event, and normalize names" do
+        expect(instance.event_named(:baz)).to be(event)
+        expect(instance.event_named(:BaZ)).to be(event)
+        expect(instance.event_named(' BaZ ')).to be(event)
+      end
+
+      it "should raise if you ask for an event that doesn't exist" do
+        expect { instance.event_named(:doesnotexist) }.to raise_error(ArgumentError)
+      end
+    end
+
+    it "should return the correct value for #retired_at" do
+      allow(version).to receive(:retired_at).with().and_return(nil)
+      expect(instance.retired_at).to be_nil
+
+      expect(klass.new(version, :foo, :retired_at => "2014-06-21").retired_at).to eq(Time.parse("2014-06-21"))
+
+      allow(version).to receive(:retired_at).with().and_return(Time.parse("2014-02-01"))
+      expect(klass.new(version, :foo).retired_at).to eq(Time.parse("2014-02-01"))
+      expect(klass.new(version, :foo, :retired_at => "2014-06-21").retired_at).to eq(Time.parse("2014-02-01"))
+      expect(klass.new(version, :foo, :retired_at => "2013-06-21").retired_at).to eq(Time.parse("2013-06-21"))
+    end
+
+    it "should turn itself into a string reasonably" do
+      allow(version).to receive(:to_s).with().and_return("boogabooga")
+
+      expect(instance.to_s).to match(/category/i)
+      expect(instance.to_s).to match(/foo/i)
+      expect(instance.to_s).to match(/boogabooga/i)
+    end
+  end
+end

data/spec/meta_events/definition/definition_set_spec.rb

@@ -0,0 +1,142 @@
+describe ::MetaEvents::Definition::DefinitionSet do
+  let(:klass) { ::MetaEvents::Definition::DefinitionSet }
+  let(:instance) { klass.new(:global_events_prefix => "foo") }
+
+  describe "construction" do
+    it "should require a global prefix for construction" do
+      expect { klass.new }.to raise_error(ArgumentError)
+    end
+
+    it "should allow creation with a Symbol for the prefix" do
+      klass.new(:global_events_prefix => :bar).global_events_prefix.should == 'bar'
+    end
+
+    it "should allow creation without a block" do
+      expect { klass.new(:global_events_prefix => 'foo') }.not_to raise_error
+    end
+
+    it "should evaluate its block in the context of the object" do
+      x = nil
+      klass.new(:global_events_prefix => 'abc') { x = global_events_prefix }
+      expect(x).to eq('abc')
+    end
+
+    it "should validate its options" do
+      expect { klass.new(:foo => 'bar') }.to raise_error(ArgumentError, /foo/i)
+    end
+
+    it "should allow declaring the global_events_prefix in the block" do
+      x = klass.new { global_events_prefix "baz" }
+      expect(x.global_events_prefix).to eq("baz")
+    end
+
+    it "should be able to create itself from an IO" do
+      require 'stringio'
+      io = StringIO.new(<<-EOS)
+global_events_prefix :abq
+
+version 1, '2014-02-15' do
+  category :foo do
+    event :bar, '2014-02-16', 'something great'
+  end
+end
+EOS
+      set = klass.new(:definition_text => io)
+      expect(set.global_events_prefix).to eq('abq')
+      expect(set.fetch_event(1, :foo, :bar)).to be_kind_of(::MetaEvents::Definition::Event)
+      expect { set.fetch_event(1, :foo, :baz) }.to raise_error
+    end
+
+    it "should be able to create itself from a file" do
+      require 'tempfile'
+
+      f = Tempfile.new('definition_set_spec')
+      begin
+        f.puts <<-EOS
+global_events_prefix :abq
+
+version 1, '2014-02-15' do
+  category :foo do
+    event :bar, '2014-02-16', 'something great'
+  end
+end
+EOS
+        f.close
+
+        set = klass.new(:definition_text => f.path)
+        expect(set.global_events_prefix).to eq('abq')
+        expect(set.fetch_event(1, :foo, :bar)).to be_kind_of(::MetaEvents::Definition::Event)
+        expect { set.fetch_event(1, :foo, :baz) }.to raise_error
+      ensure
+        f.close
+        f.unlink
+      end
+    end
+ end
+
+ it "should create a new version and pass options properly" do
+    version = double("version")
+    allow(version).to receive(:number).with().and_return(234)
+
+    passed_block = nil
+    expect(::MetaEvents::Definition::Version).to receive(:new).once.with(instance, 123, 'foobar', { :a => :b }) { |&block| passed_block = block; version }
+
+    instance.version(123, 'foobar', { :a => :b }) { :the_right_block }
+    expect(passed_block.call).to eq(:the_right_block)
+
+    expect { instance.fetch_version(123) }.to raise_error(ArgumentError)
+    expect(instance.fetch_version(234)).to be(version)
+  end
+
+  it "should return its prefix" do
+    instance.global_events_prefix.should == 'foo'
+  end
+
+  it "should raise if there is a version conflict" do
+    version_1 = double("version-1")
+    allow(version_1).to receive(:number).with().and_return(234)
+    expect(::MetaEvents::Definition::Version).to receive(:new).once.with(instance, 123, 'foobar', { }).and_return(version_1)
+
+    instance.version(123, 'foobar')
+
+    version_2 = double("version-2")
+    allow(version_2).to receive(:number).with().and_return(234)
+    expect(::MetaEvents::Definition::Version).to receive(:new).once.with(instance, 345, 'barfoo', { }).and_return(version_2)
+
+    expect { instance.version(345, 'barfoo') }.to raise_error(/already.*234/)
+  end
+
+  context "with two versions" do
+    before :each do
+      @version_1 = double("version-1")
+      allow(@version_1).to receive(:number).with().and_return(1)
+      expect(::MetaEvents::Definition::Version).to receive(:new).once.with(instance, 1, 'foo', { }).and_return(@version_1)
+
+      instance.version(1, 'foo')
+
+      @version_2 = double("version-2")
+      allow(@version_2).to receive(:number).with().and_return(2)
+      expect(::MetaEvents::Definition::Version).to receive(:new).once.with(instance, 2, 'bar', { }).and_return(@version_2)
+
+      instance.version(2, 'bar')
+    end
+
+    it "should return the version on #fetch_version" do
+      instance.fetch_version(1).should be(@version_1)
+      instance.fetch_version(2).should be(@version_2)
+    end
+
+    it "should raise if asked for a version it doesn't have" do
+      expect { instance.fetch_version(3) }.to raise_error(ArgumentError)
+    end
+
+    it "should delegate to the version on #fetch_event" do
+      expect(@version_1).to receive(:fetch_event).once.with(:bar, :baz).and_return(:quux)
+      expect(instance.fetch_event(1, :bar, :baz)).to eq(:quux)
+    end
+
+    it "should raise if asked for an event in a version it doesn't have" do
+      expect { instance.fetch_event(3, :foo, :bar) }.to raise_error(ArgumentError)
+    end
+  end
+end

data/spec/meta_events/definition/event_spec.rb

@@ -0,0 +1,146 @@
+describe ::MetaEvents::Definition::Event do
+  let(:klass) { ::MetaEvents::Definition::Event }
+
+  it "should normalize the name properly" do
+    expect { klass.normalize_name(nil) }.to raise_error(ArgumentError)
+    expect { klass.normalize_name("") }.to raise_error(ArgumentError)
+    expect(klass.normalize_name(:foo)).to eq(:foo)
+    expect(klass.normalize_name(:' FoO')).to eq(:foo)
+    expect(klass.normalize_name(" FOo ")).to eq(:foo)
+    expect(klass.normalize_name("foo")).to eq(:foo)
+  end
+
+  let(:category) do
+    out = double("category")
+    allow(out).to receive(:kind_of?).with(::MetaEvents::Definition::Category).and_return(true)
+    allow(out).to receive(:name).with().and_return(:catname)
+    allow(out).to receive(:retired_at).with().and_return(nil)
+    allow(out).to receive(:prefix).with().and_return("cp_")
+    allow(out).to receive(:to_s).with().and_return("cat_to_s")
+    out
+  end
+
+  it "should validate its basic arguments properly" do
+    expect { klass.new(double("not-a-category"), :foo, "2014-01-01", "something") }.to raise_error(ArgumentError)
+    expect { klass.new(category, nil, "2014-01-01", "something") }.to raise_error(ArgumentError)
+    expect { klass.new(category, :foo, "2014-01-01", "something", :bonk => :baz) }.to raise_error(ArgumentError, /bonk/i)
+
+    # Ruby 1.8.x's Time.parse method will accept "foo" for Time.parse and just return Time.now --
+    # which is deeply unfortunate, but there's really no good way around it.
+    unless RUBY_VERSION =~ /^1\.8\./
+      expect { klass.new(category, :foo, "unparseable", "something") }.to raise_error(ArgumentError)
+      expect { klass.new(category, :foo, :desc => "something", :introduced => "unparseable") }.to raise_error(ArgumentError)
+    end
+  end
+
+  it "should fail if you don't set introduced or desc" do
+    expect { klass.new(category, :foo, :introduced => '2014-01-01' ) }.to raise_error(ArgumentError)
+    expect { klass.new(category, :foo, :desc => 'something' ) }.to raise_error(ArgumentError)
+    expect { klass.new(category, :foo, :desc => '' ) }.to raise_error(ArgumentError)
+  end
+
+  it "should let you set introduced via all three mechanisms" do
+    expect(klass.new(category, :foo, "2014-01-01", "foobar").introduced).to eq(Time.parse('2014-01-01'))
+    expect(klass.new(category, :foo, nil, "foobar", :introduced => '2014-01-01').introduced).to eq(Time.parse('2014-01-01'))
+    expect(klass.new(category, :foo, nil, "foobar") { introduced '2014-01-01' }.introduced).to eq(Time.parse('2014-01-01'))
+  end
+
+  it "should let you set desc via all three mechanisms" do
+    expect(klass.new(category, :foo, "2014-01-01", "foobar").desc).to eq("foobar")
+    expect(klass.new(category, :foo, "2014-01-01", :desc => 'foobar').desc).to eq("foobar")
+    expect(klass.new(category, :foo, "2014-01-01", :description => 'foobar').desc).to eq("foobar")
+    expect(klass.new(category, :foo, "2014-01-01") { desc 'foobar' }.desc).to eq("foobar")
+  end
+
+  context "with an instance" do
+    let(:instance) { klass.new(category, :foo, "2014-01-01", "foobar") }
+
+    describe "validation" do
+      it "should not fail by default" do
+        expect { instance.validate!(:foo => :bar) }.not_to raise_error
+      end
+
+      it "should fail if it's been retired" do
+        expect { klass.new(category, :foo, "2014-01-01", "foobar", :retired_at => "2013-06-01").validate!(:foo => :bar) }.to raise_error(::MetaEvents::Definition::DefinitionSet::RetiredEventError, /2013/)
+      end
+
+      it "should fail if its category has been retired" do
+        allow(category).to receive(:retired_at).and_return(Time.parse("2013-02-01"))
+        expect { instance.validate!(:foo => :bar) }.to raise_error(::MetaEvents::Definition::DefinitionSet::RetiredEventError, /2013/)
+      end
+    end
+
+    it "should return and allow setting its description via #desc" do
+      expect(instance.desc).to eq("foobar")
+      instance.desc "barbaz"
+      expect(instance.desc).to eq("barbaz")
+    end
+
+    it "should return and allow setting its introduction time via #introduced" do
+      expect(instance.introduced).to eq(Time.parse("2014-01-01"))
+      instance.introduced "2015-06-30"
+      expect(instance.introduced).to eq(Time.parse("2015-06-30"))
+    end
+
+    it "should return its category" do
+      expect(instance.category).to eq(category)
+    end
+
+    it "should return its name" do
+      expect(instance.name).to eq(:foo)
+    end
+
+    it "should return its category name" do
+      expect(instance.category_name).to eq(:catname)
+    end
+
+    it "should return its full name" do
+      expect(instance.full_name).to eq("cp_foo")
+    end
+
+    it "should return the right value for #retired_at" do
+      expect(instance.retired_at).to be_nil
+      expect(klass.new(category, :foo, "2014-01-01", "foobar", :retired_at => "2013-06-01").retired_at).to eq(Time.parse("2013-06-01"))
+
+      allow(category).to receive(:retired_at).with().and_return(Time.parse("2013-04-01"))
+      expect(klass.new(category, :foo, "2014-01-01", "foobar", :retired_at => "2013-06-01").retired_at).to eq(Time.parse("2013-04-01"))
+      expect(klass.new(category, :foo, "2014-01-01", "foobar", :retired_at => "2013-02-01").retired_at).to eq(Time.parse("2013-02-01"))
+      expect(klass.new(category, :foo, "2014-01-01", "foobar").retired_at).to eq(Time.parse("2013-04-01"))
+    end
+
+    it "should become a string" do
+      expect(instance.to_s).to match(/foo/i)
+      expect(instance.to_s).to match(/cat_to_s/i)
+    end
+
+    it "should require valid data for #note" do
+      expect { instance.note("", "me", "something here") }.to raise_error(ArgumentError)
+
+      # Ruby 1.8.x's Time.parse method will accept "foo" for Time.parse and just return Time.now --
+      # which is deeply unfortunate, but there's really no good way around it.
+      unless RUBY_VERSION =~ /^1\.8\./
+        expect { instance.note("foobar", "me", "something here") }.to raise_error(ArgumentError)
+      end
+
+      expect { instance.note("2014-01-01", "", "something here") }.to raise_error(ArgumentError)
+      expect { instance.note("2014-01-01", "me", "") }.to raise_error(ArgumentError)
+    end
+
+    it "should allow you to add notes, and return them" do
+      instance.note("2014-01-01", "me", "this is cool")
+      instance.note("2013-02-27", "someone else", "whatever")
+
+      expect(instance.notes.length).to eq(2)
+
+      note_1 = instance.notes[0]
+      expect(note_1[:when_left]).to eq(Time.parse("2014-01-01"))
+      expect(note_1[:who]).to eq("me")
+      expect(note_1[:text]).to eq("this is cool")
+
+      note_2 = instance.notes[1]
+      expect(note_2[:when_left]).to eq(Time.parse("2013-02-27"))
+      expect(note_2[:who]).to eq("someone else")
+      expect(note_2[:text]).to eq("whatever")
+    end
+  end
+end