Documentation & Testing

Proposals
1

Continuing the discussion from Testing individual components is easy:

I’m creating a new topic because I realised the original topic was about components as in “parts of ember” and what I was talking about what “instances of Ember.Component”. Apologies everyone!

The crux of this is that I’m having a tricky time unit testing Ember.Component objects. It’s interesting to call it unit testing given that an Ember.Component has two kinds: 1. A template-only variety which if I understand it correctly creates an Ember.Component instance behind the scenes, and 2. A variety that has both a template and a explicitly instantiated Ember.Component object.

How can I test the functionality in each of those cases? Ordinarily, for simple cases, I’d just skip it, but the thing I’m currently working on is quite complex (it’s a kind of WYSIWYG editor, but it has its own model and deals with multiple objects). I’m really interested in doing TDD with Ember (I’ve been sold on TDD for quite a while). Chances are I’ve got an architectural issue which is perhaps why it’s so hard for me to unit test these things.

I guess I’m probably viewing things as a series of scoped isolated integration tests. I don’t generally see there as being much of an actual difference between an integration test and a unit test most of the time - it’s just a matter of where you draw the lines in the sand.

Basically, I’d like to test the functionality of this Ember Component that I’ve built, but can’t seem to work out how to do so as an isolated unit.

One other thing is, could we possibly consider putting testing into the documentation around all of the code examples? I reckon that’d provide us all with an excellent resource in two ways: 1. It’d build a library of user-centric tests (Users of Ember, I mean - ie Programmers as consumers of Ember’s API), but 2. It’d also provide a massive pedagogical resource, making the possible uptake of ember much faster.

1 Like
2

Okay so someone answered another, simpler question I raised on Stack Overflow that essentially answers this issue a little, too…

I’d still like to see more documentation around this, if possible, which I can’t really write, because although I can implement his solution, I don’t really understand why to use stop() and start(), or why I have to put an Em.run.schedule call inside the Em.run outer call… It’d be heaps nice to know these things. (runloops, eh? :-))

Hopefully it’s reasonably obvious that this stuff isn’t the easiest in the world to build tests for… it’d be nice if it was somewhat addressed - either through documentation or a nicer API for testing with? Anyone have any thoughts?

3

Could we possibly consider putting testing into the documentation around all of the code examples? I reckon that’d provide us all with an excellent resource in two ways: 1. It’d build a library of user-centric tests (Users of Ember, I mean - ie Programmers as consumers of Ember’s API), but 2. It’d also provide a massive pedagogical resource, making the possible uptake of ember much faster. Anyone have any thoughts on that?

4

I am working on an update to the Ember guide which will hopefully be added by EmberConf. With this comes solid docs and examples of how to unit tests your ember apps, including components.

As a preview, testing an Ember component will be as simple as this (not definitive):

moduleForComponent('pretty-color');

test('renders green', function() {
  var component = this.subject({ color: 'green' });
  this.append();
  equal(component.$().html(), '<span class="color: green;">Content</span>');
});
5

That sounds really sweet! :slight_smile: I’d love it if you could ensure to explain or at least reference the API for what moduleForComponent, subject() and append() all do, because that looks opaque to me (I’m sure you’d do that as our documentation tends to be excellent along that vein).

I think we need to be teaching testing from the get-go, and we could do that by incorporating it into all of our examples on the documentation site. Tests are great because they can illustrate intent, and along with proper documentation, they tell the full story of the architecture of something.

None of the examples on the ember documentation site have tests that I’ve seen, and yet we demand them from ourselves: it’s impossible to become an ember codebase committer without using tests; in fact whenever someone has a problem, we tend to ask them to create a jsbin, which is effectly a micro test environment isolated to that particular context.

I don’t want to sound like a broken record, but the effects of this would be great for Ember’s PR in a tangible sense: wrappering all examples in tests would provide an approachable mechanism for learning Ember because they explain why things happen as they do. Tests provide a CONTEXT for code. It’s the context that educates.

The reason for that is… if all examples and explanations are well tested, as a new user learning Ember from zero to committer all I have to understand is basic javascript and how to use qunit. I can look up any of the API documentation and all of the examples are shown along with tests for the examples working proving they’re doing what they’re doing.

The best part is, the example tests become part of Ember’s test suite, and we know that Ember is hugely tested from an application level, because all of the tests will be exercising as much of the interfaces as we explain. It would also encourage people to write documentation and work on the codebase - to use a marketing term, we’d be building a very soft gradual engagement ramp.

I’m very interested in this, because it’d let me start to contribute to Ember, too :slight_smile: Right now, the ramp up in terms of difficulty is still massively high. It’d be great if we could make the ramp up less steep by simply encouraging people to contribute from the get go. In order to do that, we have to work on the accessibility of it, and I seriously think handing people qunit and saying “learn this to learn Ember” is a great way to do that.

6

@JulianLeviston will you be at ember conf? I would love to meet you and discuss this further.

7

Awww… I would love to so much to meet all you guys and stuff, but I’m not going to be able to this time. It really sucks.