Epic: Release Interactors Beta, Platform Alpha #683
Comments
|
Updated layout: interactors/
platform/
|
Small Updates
QuestionsSmall
Medium
Large
Preview of our current progress: Netlify. |
That weird since interactors work in the DOM. Maybe node 12 is required to build the interactor library?
Yes. It's hard to imagine writing a test case without using the Page interactor to visit the url, and since that's what you'd also do to assert that you're on the proper URL, or what the page title is, I'd say it's critical to cover
Is this on the index page?
I'd say it's safe to say that we'll get it working, or if there is a workaround that needs to happen, then we can include that in our documentation.
action:
createInteractor('DatePicker')({
actions: {
open: (picker) => picker.find(Button).click()
}
}); |
I'd also add that if you are going to write your own interactors, never fear! You can still use the built in interactors in the manner in which I alluded to before, you would just delegate to them. Does that mean we should have a section on using interactors from interactors?
|
|
@minkimcello @jenweber Had a look over the initial preview, and as I mentioned before, it's coming along very nicely. I've separated my thoughts into structural, stylistic, and content StructuralI don't know if this is something intrinsic to docosaurus, but it feels like the content is broken up into tiny pages-. This is my own personal preference, but when I'm reading docs, I prefer to have the navigation go to internal anchors within a single page rather than have 10 different pages. Maybe this will change as the individual sections get larger? /cc @jorgelainfiesta StylisticI'm a fan of using long options in documentation, and short options in usage, so for example, I'd say Contentstatements like this on the builtins page:
or this on the locators, filters and actions page:
seem to imply that locators, filters and actions are related to creating your own interactors, when in fact, they are key to the builtin interactors as well. Maybe we can tweak the language to have a more universal tone Locators
Also, it might be worth dropping in an actual Filters
Writing your own LocatorsOn the four things to decide on how to build your custom interactor, I think the example of using the class name is not a good pattern. Is the css class name something that a user would identify? Not really. Usually, a checkbox would be identified by its corresponding label. That may not be available with an interactor. Also, delegating to another interactor is definitely part of the story in creating custom interactors. Maybe our custom interactor should be a checkbox with a label that delegates to the internal checkbox for it's toggle action? |
|
Here is a dump of my notes after a read of the interactor guide. I was in a bit of a hurry, so apologies if it's a bit rough, but I figured getting it jotted down was the most important thing: Builtin Interactorsassertions should generally use a filter + would work, the friendlier form would be something more like Also, I'd assert on the
Can we get a preview here? "some things in common" might be better as more specific. What are those things? Actions, which advance the state of your app, and filters which match on it and help you do things like make assertions locators, filters, and actions page
Again, I think that stating the purpose before we introduce the term is helpfuul. How about something like "All interactors have some things in common, whether they are built-in or written by you. They have to be able to find elements in the page, manipulate them like a user would, and ultimately make assertions based on how they appear. To do these things, interactors use Locators, actions, and filters"
How about "finding what to act upon?" since not every interactor has a click actions
I'd rephrase this a bit because finding buttons isn't what users do so much as identify them and divine their purpose and perhaps use an example. Maybe "A typical user identifies a button by the words printed across it, so for example, they would think of a button with the word 'Submit' on it as the "Submit" button. Interactors use This code snippet has a syntax error: Button({
id: 'submit-button-1',
title: 'Sign Up Form',
visible
}).exists();it should be `visible: true``
We don't fully understand this issue, but we should unpack it if we're going to reference it in a guide.
In this section, I think it would be good to really play up the importance of filters in assertions with explanatory text. Something like "filters can be very convenient for finding matching UI elements, but where they really shine is in making assertions about what you expect your application to be showing. It also might help to include that this is the equivalent of 'expect' in Jest, and Finally, the rule for when to use Writing interactorsThe example, which uses an id for the locator goes against the advice we gave for interactor in the previous section. The id is for computers. I know we want to make it different, but maybe we can use
What does "target" mean? It could mean a couple of things, so maybe it's worth expanding on this to say that the selector chooses a flat list top level elements that will be considered. Filters and locators are used to narrow this list.
The code snippet only has a rendition in Platform, not Cypress or Jest
Rather than put the implementation first here with the table cell interactor, talking about how you can use filters to make very complex, yet very readable assertions is one of the great strengths of interactors. Leading with an example of how awesome it is to use the power filter is going to sell more than the somewhat large implementation, which without seeing the benefit first, is hard to evaluate in context. Something like this: TableCell({ columnTitle: 'politics', row: 3 }).has({ value: '$600' });GeneralIt looks like there is some flash / jank on the navigation? where they resize momentarily? |
|
General feedback:
Specific feedback:
I find this somewhat confusing. While "This string argument is used by the Locator" is technically correct, the follow up is then: what is a locator, and that is not really explained. Even though this is somewhat confusing, I would almost advocate to refer to the actual value as the locator, and so the function which is passed to the specification is a locator function and it evaluates to the locator. I think this would be easier to understand.
Is this really true?
This is a bit strange, maybe something like "Later you will learn how to add your own filters to interactors", or something like that? Button('Submit').has({ id: 'submit-button-1' });This example doesn't seem very realistic, can we use a better example, like asserting on the value of a text field, for example? Button({ id: 'submit-button-1' }).is({ visible });This should probably be: Button({ id: 'submit-button-1' }).is({ visible: true });
The section on
"strange" seems like a very charged word, can we choose something more neutral like "unusual" or "non-standard" or something?
Can we start with something even simpler? Something like
There is a very significant jump in complexity in this example. This seems like the type of the interactor we should bundle, but it doesn't seem great as a teaching aid. |
@jorgelainfiesta have you noticed this problem? |
|
@jnicklas @cowboyd at the end of the quick start, we're thinking of adding some real life examples like this:
import { Button, Page, test } from 'bigtest';
import { Modal } from './MyModalInteractor';
export default test('BigTest')
.step(
Page.visit('/'),
Button('Sign In').click())
.assertion(
Modal({ id: 'sign-in-modal' }).exists();
Button('Log In').exists());👆 it's just a rough example but the purpose here is to show an example of UI interaction that is usually a pain in the butt to test. due to my lack of experience in writing tests, i'm having a hard time trying to think of an example that people would want to see. is there a particular interaction that we should showcase here? |
We want to release what we have at the beginning of December with a bang, and what that means is that we want everything that we do have to be "swipe to unlock". As it currently stands, we feel that the interactors as a standalone library fits that bill. You can take it and install it in Jest, Cypress, Mocha, and yes, in our own runner, and experience immediate, palpable benefit.
On the other hand, the runner, test syntax, and dev experience, etc... still feels a bit rough around the edges and some time is needed for it to settle. Part of this is that a library is simpler to drop in than something that has a CLI and lots of moving parts. The other is that we still have a lot that feels experimental in our runner.
As a result, we are going to push the interactors as the main feature of the release, and then bill everything else as Platform that not only contextualizes interactors with the important motivating factors about why we are doing all this work, but also provides an on ramp for early adopters that want to get started with writing the tests in a new way.
Along side the code, we want to release an entire site dedicated to bigtest that will hang directly off of the main
frontside.comwebsite:https://frontside.com/bigtestthat will contain everything that users will need to know about bigtest. This will including marketing material such as rationale, and value proposition as well as detailed technical guides for the various pieces which today include interactors and platform. 90% of our effort will be focused on the interactor story since we feel that this is what is most actionable and ready as of today. But we'll spend 10% of our effort on the large picture and a very minimal guide for starting the@jorgelainfiesta, @cherewaty and I created draft sitemap for the release site that will contain all of the relevant pages/sections. So once this sitemap is in place, each page can be picked off and executed, or executed in pieces. The person spearheading each piece is marked next to that piece. That doesn't necessarily mean that that person will be doing all of the work on that section, but it does mean that they'll be the main point of contact for it.
- Focus on the cross platform story, “ideas refridas” from bigtestjsi.io
- CTA: getting started with bigtest platform
- Conversion metrics: npm installs, users in discord
@bigtest/cypressExtract cypress integration into separate@bigtest/cypresspackage in separate workspace #759composable filters @jnicklas @cowboyd Composition of Interactor filters and locators #773WONTFIXaccess filter values inside filters and actions Composition of Interactor filters and locators #773WONTFIXperform()API https://github.com/thefrontside/bigtest/discussions/770The text was updated successfully, but these errors were encountered: