gistfile1.md

Background

This article is a response for the following feature:

@javascript
 
Feature: Filter enable/disable
 
Scenario: Using the filter with resources
  Given I am logged in
  And I have the following allocations
    | resource | start time | end time | project name |
    | tom jones | now | 5 days from now | company 1 |
    | bob timmy | now | 5 days from now | company 2 |
  And I visit account page
  Then I should be able to filter my resources
 
Scenario: Using the filter without resources
  Given I am logged in
  And I visit account page
  Then I should not be able to filter my resources

Title

The title should be as specific as possible. When I read "Filter enable/disable", I'm not sure what filter you're talking about. For example, what if there are more filters in the application? And even if there aren't, we likely won't remember to change the feature title when we add more filters, so better to be as explicit as possible from the start.

So, one alternative to the current title would be

Feature: Project filter availability

My formula is usually target state/action. I.e., the feature can describe the states that target can be in, or what happens when we do action to target. This is not a hard rule, but I find it helps me organize my features.

Motivation

It's useful to add a small paragraph explaining why the feature exists and who it will benefit. It's useful to do it for a few reasons:

1. This may be your final defense against implementing a useless feature, or maybe it will cause you to find a simpler solution than the one you had in mind.
2. It will help future readers understand why the feature exists.
3. It will help you understand when it's not needed anymore.

In this case, we could have something like

We don't want to waste a user's time by making controls available when
they're useless, so we only enable project filters when it makes sense.

There's a more formal approach people use: So that I [can reap some benefit], as [someone], I (don't) want to [do something]. I think it's too formal, but on the other hand you may find the consistent format helps.

Background

You can extract common consecutive steps at the start of a feature into a Background section. There's no point in repeating the same things over and over--it's boring for you and for other readers:

Background:
  Given I am signed in as a user

Scenarios

A scenario explains what should happen in a certain context. The obvious first question is, what are the significant contexts that should be mentioned?

There is a rule of thumb we can apply when testing quantities of elements which guided me when coming up with those scenarios:

• Add a scenario for when no elements exist.
• Add a scenario for when 1 element exists.
• Add a scenario for when many elements exist.
• (learned recently) Add a scenario for when lots of elements exist (i.e. think about pagination, etc).

In this feature, we have 3 kinds of elements: projects, project states (active/inactive), and project users.

Based on the guidelines I mentioned above, what I know of Allocate (which is very little) and my expectations of how it should work. I came up with the following scenarios:

Scenario: no projects
  Given my account has no projects
  When I look at the allocation filters
  Then I should see I can't filter allocations by project

Scenario: no active projects
  Given my account has a few inactive projects
  When I look at the allocation filters
  Then I should see I can't filter allocations by project

Scenario: some inactive projects, 1 active project
  Given my account has a few inactive projects
  And my account has 1 active project
  When I look at the application filters
  Then I should see I can't filter allocations by project

Scenario: 1 active project with more than 1 user
  Given my account has the following active project:
    | name | The Secret of Monkey Island SE |
  And 2 users are allocated to "The Secret of Monkey Island SE":
  When I look at the application filters
  Then I should see I can't filter allocations by project

Scenario: more than 1 active project
  And my account has 2 active projects
  And each project has 1 user allocated to it
  When I look at the application filters
  Then I should see I can filter allocations by project

This list is not exhaustive because the more tests we add, the longer tests will take to run. I also didn't include pagination here (the lots case) because I have no idea how that should work--I'm leaving that up to you.

As with UIs, scenarios should have as few elements as needed, and no more than what's needed. When it seemed to me the there could be some ambiguity, I split the step in 2:

Given my account has the following active project:
  | name | The Secret of Monkey Island SE |
And 2 users are allocated to "The Secret of Monkey Island SE":

instead of (what has 2 users, the project or the account?):

Given my account has 1 project with 2 users

There are a few things I've omitted. There are no start dates or end dates, and no user names as well. I didn't think they were needed for the feature, and they could even confuse people.

I also didn't clarify what it means for a project to be active/inactive, or what it means for a user to be allocated to a project. These are questions that should be answered in the project glossary. If there isn't one, we can at least use the record factories to communicate that. For example, if you create a project like this:

create :active_project

Then one can look at the project factory to understand what it means for a project to be active.

And that's it. Sorry for the long, long comment, but I hope it helps.