New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Core functionality of Ataru - how to implement it #12

Closed
nerdbabe opened this Issue Aug 11, 2014 · 15 comments

Comments

Projects
None yet
5 participants
@nerdbabe
Member

nerdbabe commented Aug 11, 2014

Today we talked about the general design of Ataru.

Our idea is:

1.The developer has to create a setup module (setup means there have to be all requirements you need to run the application and the application itself) and the markdown files.
2.Ataru extracts the code samples out of markdown files.
It creates a new test class for each markdown file that inherites from Mini::Test and the setup module. It wraps the code samples into test methods and adds them to the related test class.
3.Then all created test methods will be run.
4. There is an output that shows the results.

Question is: Is this a good solution? Or is there something better/easier?

@nerdbabe nerdbabe added this to the sprint 2 milestone Aug 11, 2014

@nerdbabe nerdbabe added the question label Aug 11, 2014

@nerdbabe nerdbabe assigned schultyy and unassigned schultyy Aug 11, 2014

@kazjote

This comment has been minimized.

Show comment
Hide comment
@kazjote

kazjote Aug 11, 2014

Looks good to me! 👍

kazjote commented Aug 11, 2014

Looks good to me! 👍

@railsbros-dirk

This comment has been minimized.

Show comment
Hide comment
@railsbros-dirk

railsbros-dirk Aug 11, 2014

Overall that sound reasonable to me, still I have some questions/suggestions:

  1. It would be nice if Ataru comes with generator to help you getting started with the setup module.
  2. What exactly will be tested in the tests? Do you need to provide assertions in the example itself? Thinking about this, I would not mind doing this… If not, how do determine if a test case was run successfully or not?
  3. Ataru should be accessible programmatically (i.e. from a Rake-Task) to make it easy to integrate it into your build process. This is usually not very difficult, just make sure you're not putting too much logic into the executable ;-)

You're doing well young padawans ;-)

railsbros-dirk commented Aug 11, 2014

Overall that sound reasonable to me, still I have some questions/suggestions:

  1. It would be nice if Ataru comes with generator to help you getting started with the setup module.
  2. What exactly will be tested in the tests? Do you need to provide assertions in the example itself? Thinking about this, I would not mind doing this… If not, how do determine if a test case was run successfully or not?
  3. Ataru should be accessible programmatically (i.e. from a Rake-Task) to make it easy to integrate it into your build process. This is usually not very difficult, just make sure you're not putting too much logic into the executable ;-)

You're doing well young padawans ;-)

@nerdbabe

This comment has been minimized.

Show comment
Hide comment
@nerdbabe

nerdbabe Aug 11, 2014

Member

Thanks Dirk,

  1. Okay, that sounds good. We have to figure it out how we can do that.
  2. At the moment we grap the code samples and just run them. There are no assertions. It's like a skeleton MiniTest method. Maybe that is not the best way to test the samples but we have no good idea to do it in another way.
  3. Good point. Let's find out how we can do that^^.
Member

nerdbabe commented Aug 11, 2014

Thanks Dirk,

  1. Okay, that sounds good. We have to figure it out how we can do that.
  2. At the moment we grap the code samples and just run them. There are no assertions. It's like a skeleton MiniTest method. Maybe that is not the best way to test the samples but we have no good idea to do it in another way.
  3. Good point. Let's find out how we can do that^^.
@schultyy

This comment has been minimized.

Show comment
Hide comment
@schultyy

schultyy Aug 11, 2014

Member

Concerning the actual test case for a code example, I would say if it runs without throwing an exception it passed.

Member

schultyy commented Aug 11, 2014

Concerning the actual test case for a code example, I would say if it runs without throwing an exception it passed.

@railsbros-dirk

This comment has been minimized.

Show comment
Hide comment
@railsbros-dirk

railsbros-dirk Aug 11, 2014

  1. The generator would be something for later (a.k.a. rabbit hole). But you should look at the Thor generators. Unfortunately, this library is awesome but has terrible documentation…
  2. Sound legit for me. Especially for existing projects. But you could recommend to use assertions in the examples. This could even improve the readability of the examples. What do you think @schultyy?
  3. You maybe want to look at Thor for the executable as well… If you have any questions, just ask :-)

railsbros-dirk commented Aug 11, 2014

  1. The generator would be something for later (a.k.a. rabbit hole). But you should look at the Thor generators. Unfortunately, this library is awesome but has terrible documentation…
  2. Sound legit for me. Especially for existing projects. But you could recommend to use assertions in the examples. This could even improve the readability of the examples. What do you think @schultyy?
  3. You maybe want to look at Thor for the executable as well… If you have any questions, just ask :-)
@moonglum

This comment has been minimized.

Show comment
Hide comment
@moonglum

moonglum Aug 11, 2014

In my documentations I will often write examples like that:

a = 1 + 2
a #=> 3

Maybe you could take that and transform it into a test case like that:

def test_something
  a = 1 + 2
  assert_equal 3, a
end

In my experience the "fat arrow" (=>) is a common symbol to say: This is the result of this line. And as a reader I would expect that this is really the result of that line 😉 So ataru could check if that is really the case.

moonglum commented Aug 11, 2014

In my documentations I will often write examples like that:

a = 1 + 2
a #=> 3

Maybe you could take that and transform it into a test case like that:

def test_something
  a = 1 + 2
  assert_equal 3, a
end

In my experience the "fat arrow" (=>) is a common symbol to say: This is the result of this line. And as a reader I would expect that this is really the result of that line 😉 So ataru could check if that is really the case.

@moonglum

This comment has been minimized.

Show comment
Hide comment
@moonglum

moonglum Aug 11, 2014

I think that is the more common way to show an assertion in examples than putting an assert_x in there 😉

moonglum commented Aug 11, 2014

I think that is the more common way to show an assertion in examples than putting an assert_x in there 😉

@moonglum

This comment has been minimized.

Show comment
Hide comment
@moonglum

moonglum Aug 11, 2014

Also this would give me the great pleasure to record some screencasts about regular expressions 😉 😉

moonglum commented Aug 11, 2014

Also this would give me the great pleasure to record some screencasts about regular expressions 😉 😉

@railsbros-dirk

This comment has been minimized.

Show comment
Hide comment
@railsbros-dirk

railsbros-dirk Aug 11, 2014

@moonglum Like the idea… Anyways, there should be more than just executing.

railsbros-dirk commented Aug 11, 2014

@moonglum Like the idea… Anyways, there should be more than just executing.

@schultyy

This comment has been minimized.

Show comment
Hide comment
@schultyy

schultyy Aug 11, 2014

Member

@railsbros-dirk At first I would start with execution and later on with more advanced topics like assertions you discussed. This also gives @moonglum some time to record screencasts :)

Member

schultyy commented Aug 11, 2014

@railsbros-dirk At first I would start with execution and later on with more advanced topics like assertions you discussed. This also gives @moonglum some time to record screencasts :)

@railsbros-dirk

This comment has been minimized.

Show comment
Hide comment
@railsbros-dirk

railsbros-dirk Aug 11, 2014

@schultyy full ack on that one :-)

railsbros-dirk commented Aug 11, 2014

@schultyy full ack on that one :-)

@nerdbabe

This comment has been minimized.

Show comment
Hide comment
@nerdbabe

nerdbabe Aug 11, 2014

Member

Okay, i think it woul be better to discuss the different points in different issues:

  1. Generator -> #17
  2. Improve tests -> #19
  3. Executable -> #18
Member

nerdbabe commented Aug 11, 2014

Okay, i think it woul be better to discuss the different points in different issues:

  1. Generator -> #17
  2. Improve tests -> #19
  3. Executable -> #18
@nerdbabe

This comment has been minimized.

Show comment
Hide comment
@nerdbabe

nerdbabe Aug 11, 2014

Member

So, if ypu agree with our idea of the core functionallity we would implement it in the way it is described above.

Member

nerdbabe commented Aug 11, 2014

So, if ypu agree with our idea of the core functionallity we would implement it in the way it is described above.

@moonglum

This comment has been minimized.

Show comment
Hide comment
@moonglum

moonglum Aug 12, 2014

I agree with your idea 👍

moonglum commented Aug 12, 2014

I agree with your idea 👍

@nerdbabe

This comment has been minimized.

Show comment
Hide comment
@nerdbabe

nerdbabe Aug 18, 2014

Member

And the last one:
Validate Codesample goes to #30

Member

nerdbabe commented Aug 18, 2014

And the last one:
Validate Codesample goes to #30

@nerdbabe nerdbabe closed this Aug 18, 2014

@nerdbabe nerdbabe reopened this Aug 18, 2014

@nerdbabe nerdbabe closed this Aug 18, 2014

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment