Forem: Mary

Pest-Driven Development: Testing Routes For Authenticated Users in Laravel Jetstream

Mary — Mon, 18 Sep 2023 17:15:45 +0000

I'm blogging along with the laracasts series Pest Driven Laravel created by Christoph Rumpel as I work on a project I hope to open source. I'm just documenting how I'm working, the resources I'm using, the problems I run into and some cool things I'm reminded of as I develop.

I'm moving forward with a new understanding of my goal, and already I can tell that my goalpost has shifted. This past week involved a lot of failing. I'm excited about that because while I do enjoy all the resources I wrote about in my last blog post, I always learn the most by breaking things in new ways and paying a lot of attention while I fix it. It's easier to pay attention when I'm trying to fix something. This year's Laracon had an excellent talk by Joel Clermont about getting unstuck which had a particularly tricky debugging situation as its final example. No spoilers, but I knew exactly what the problem was because I've done it in Python.

I also moved to a new blog writing method now that I've put out all the fires I can find so everything's going to be in past tense this time.

I made a new test file just for task.show. This is the named route we're going to be talking about today. It displays a navigation bar and the details of one task that's already been created.



<?php

use App\Models\User;
use App\Models\Task;

use function Pest\Laravel\{get};

it('gives back successful redirect response for unauthenticated users for the tasks.show page', function () {
    $task = Task::factory()->create(['task_description' => 'Test Task 1', 'sheets_id' => 1, 'public' => false]);
    get(route('tasks.show', ['user' => $user, 'task' => $task]))->assertStatus(302);
});

The test ran and it passed.

Failing With A Default `Factory`

The next step was to actually test the routes with a logged-in user. Building on the principles I laid out for myself, I decided to test the smallest thing I can: the show method for a single task. So I wrote this based on the progress I've made in the course so far:



it('can be accessed by verified user', function () {
    // Arrange
    $user = User::factory()->create();
    $task = Task::factory()->create();

    // Act & Assert
    $this->actingAs($user)
        ->get(route('tasks.show'))
        ->assertOk();
});

It failed. Normally that's step 1, but in this case I already had a task view written and I was expecting it to pass. This test has some new stuff going on:

$user = User::factory()->create();: Here, we return a facade which uses a factory to create and store a new instance of User in the testing database. These records are created during the test instantiation and destroyed when the test is complete, so they'll look different every time pest is run. Pest manages the creation and deletion of these records for you. It relies on php faker to seed random data so you don't have to write seeders. There's also a python faker for my fellow polygots who may or may not have spent a bunch of hours writing their own seeder only to be told Laravel already has a good one. Turns out Python has a good one too. Oops.
$this->actingAs($user)...: I still cannot tell you what $this is with confidence (is it the testing context??), but I can tell you that actingAs($user) is a chained method which accepts our temporary $user as a parameter and allows us to make requests to a route as that fake user. This comes from Laravel Passport, the dependency jetstream uses to spin up an OAuth2 server implementation for us. I've been working through a book about OAuth2 for almost 3 years. It is so refreshing to bump into OAuth2 while searching docs as opposed to bending to its will.
$this->actingAs($user)->get(route(tasks.show))...: Now we've come to same old version of our previous get request. This time it's being called with more contextual information stored in $this.

The error comes from eloquent, the built-in Laravel dbms. Our create() method tried to commit a Task to the database without required attributes. It's calling out the sheets_id attribute because it's listed first, but there's going to be a few more problems we can fix by writing a [Factory]() right now.

Task Factory

When I created my task model, I specified I wanted a factory to be automatically created for me. It's already there in {{root}}\database\factories\TaskFactory.

I also already have a working user factory provided by Laravel. It's in /vendor/laravel/framework/src/Illuminate/Database/Eloquent/Factories/Factory.php. More general code for factories is also already in your app at /vendor/laravel/framework/src/Illuminate/Database/Eloquent/Factories/Factory.php.

In general, we can use faker generators; you can find the generator class in your ./vendor/fakerphp/faker/src/Faker/generator.php directory if you want to see a list real quick. In this case, a few attributes I'm going to keep consistent just so I'm seeing consistent data across a test if I need to see it with dump() later.

Here's the factory I ended up with:



class TaskFactory extends Factory
{
    /**
     * Define the model's default state.
     *
     * @return array<string, mixed>
     */
    public function definition(): array
    {
        // get a date sometime in the next two months
        $currentDateTime = Carbon::now();
        $dateTime = $currentDateTime->addDays(rand(2, 60))->toDateString();
        $currentDateTime = $currentDateTime->toDateString();
        $name = $this->faker->firstName();
        $sheetsId = $name . $currentDateTime;
        return [
            'sheets_created_at' => "",
            'sheets_id' => $sheetsId,
            'name' => $this->faker->randomDigitNotNull(),
            'author' => $this->faker->firstName(),
            'start_date' => $dateTime,
            'start_time' => $dateTime,
            'public' => rand(0, 1) == 1,
            'client_address' => $this->faker->streetAddress(),
            'task_description' => $this->faker->text(),
            'destination' => $this->faker->streetAddress(),
            'volunteer' => "",
            'status' => "unassigned",
            'contact_information' => $this->faker->text(),
        ];
    }
}

The other line to notice here is $currentDateTime = Carbon::now() and $dateTime = $currentDateTime->addDays(rand(2,60))->toDateString();. I wanted to create a start_date and start_time between now and 2 months for now, because that's about the amount of time I'm seeing most tasks scheduled. If that was all I wanted I could use $dateTime = Carbon::now()->addDays(rand(2,60))->toDateString();, but I also want to see a sheets_created_at with a really similar timestamp to the created_at in my database timestamps.

I'm using carbon to get my epic $currentDateTime timestamp (pun intended this time). I know of Carbon from Laravel Up And Running, so I used these handy digitalocean tutorials on Getting an Easy Datetime in Laravel and Manipulating The Date And Time to copy and paste. Then I googled again to assign it to my attributes as a string. I'm going to format this output later but right now I have my test set up and nothing is null that shouldn't be nullable.

So far I:

wrote a failing test to hit the route as authenticated
wrote a blade template
added my route to web.php
told TaskController.php what to do when a request hits the route
modified my test to include $actingAs before the get and include User and Task factories through facades
wrote a Task factory and used dump() to check that my creates a complete, random $task I can pass to my route

That's everything the course teaches about showing detail, I think. It should pass now, right? Right?

Failing Without a User Group

No, it didn't pass. Now I'm getting an error from my navigation bar template in blade that wants the name and id of the organization associated with my user. I have a fake user, a fake task, and no fake organization. Not going to lie, it took me a while to realize what this error meant. There's not much we can do in jetstream without running into this issue because the navigation bar is on every page and users really should be associated with teams at all times.

This is a problem I signed up for. I'm coding along with the course instead of going ahead through it because I want to make all of these mistakes now. I'm VERY tempted to reach out and ask for help (or thank people for being awesome and making course content), but I can be pretty thick-headed and I know that if I don't understand why I'm doing these things and fix them as I break them I'll learn them for ever ever. If I don't, I'll lose time (potentially for years) forgetting things I don't rememeber learning. That's why I'm not a copy and paste from stack overflow person and never will be. Unless it's a super elegant one-liner like public: rand(0, 1) == 1 which I'm sure I understand fully before I use it. Should I compromise? Yes. Would I compromise if I was being compensated for my time? Also yes. Moving on.

In order to display my template, I need to create a user organization, but it can't just be any user organization. They have to have a relationship or the test will still fail. My $user is going to have a belongs to relationship to the personal_team provided by jetstream. I will sometimes refer to this personal_team it a team because that is what jetstream named it. I also sometimes call it an organization, because that is what it represents in my problem domain. There's this great solution on laracasts.com, which helped me find the Laravel Documentation addressing the problem.

Now my test looks like this:



it('returns 200 on GET request for authenticated user @ tasks.show', function () {
    // Arrange
    $user = User::factory()
        ->hasAttached(
            Team::factory()
                ->state(function (array $attributes, User $user) {
                    return ['user_id' => $user->id, 'personal_team' => true];
                }),
        )
        ->create();
    $task = Task::factory()->create();

    // Act & Assert
    $this->actingAs($user)
        ->get(route('tasks.show', ['task' => $task, 'user' => $user]))
        ->assertOk();
});

And it passes. There's NOTHING like a passing test case.

Conclusion

After getting tasks.show to pass for authenticated users, I added new files for each view that already existed in my previous SuccessfulGetResponse2.php except /home. Then I used variations of the method described above to produce this output:

I Don't Care How You Pronounce SQL

Mary — Sun, 17 Sep 2023 04:52:29 +0000

For some reason The Algorithm(TM) keeps showing me posts about weather SQL should be pronounced S-Q-L or sequel. It's renting space in my head and it's Saturday so I wanted to rant about it.

When I was in college, I was publicly corrected for pronouncing SQL 'es-quel' and it caused a lot of shame. 'es-quel' is more on the sequel side of the argument, but I haven't run into it since. It's also how the instructor of the only database course I had ever taken pronounced it in the videos. I don't know if this was because he was saying it as a part of PostgreSQL or because he had a particular accent, but he was the only person I'd ever heard say SQL out loud before.

I was at a really exciting point in my own learning, because I was just moving from writing html/css/js to actually displaying data from queries in my projects on localhost. This felt extremely powerful and exciting. I was a freshman and taking an intro course in C as part of my actual coursework, but this SQL was independent learning and I was excited to talk about it with people who knew more than me. In this case, upperclassmen. I was considering joining the campus ACM chapter.

The room was full of CS and IST majors on the S-Q-L side, and the feedback was devastating. It was only a few sentences but I suddenly felt really, really small. I didn't just start a conversation by saying "hey, guess what guys? I know how to pronounce es-quel", either. I was going to ask a question about a join which is now long-forgotten and never got asked because I was absolutely flushed with embarrassment. I never did join that chapter of the ACM. But I did go home and google it to find that either pronunciation is acceptable and it seemed like a cruel punchline for the rejection I was feeling.

It's been a few years and I've developed a list of context-specific terms I use to actively avoid pronouncing SQL: schema, DBMS, database, postgres, query, join/select, store. They're never quite right for the context but I have also never been called out on it.

I'm reminded my experience is not unique (though it's a little overblown by rumination) through some comments I'm seeing tonight and because of conversations I've had with people in the decade since I went to college irl. I've noticed anecdotally that:

people who have read it and haven't heard it said and/or learned mySQL first tend to say S-Q-L
people who have taken courses with audio especially about PostgreSQL or Microsoft SQL Server tend to say sequel
people who use SQLite are kind of wildcards

I think there's a subtle form of unintentional gatekeeping going on here. Many people stick to the form they themselves have been corrected to and correct others to that form with good intentions. Maybe it was lucky that the first time it happened to me was in a conversation during which a few other problematic things were said, because that prompted me to actually look it up and ask a few professors who all said it really doesn't matter, usually with the caveat of their preference and why. I had multiple office hours where professors basically reacted with the exact same vibe D. Richard Hipp has in this changelog episode. But the time it takes to correct someone on pronunciation that truly doesn't matter sometimes prevents the thing that person was going to say next like it did with me.

These conversations mostly happen when someone is trying to establish context before explaining something or asking a question. Even if they're just expressing enthusiasm, I think it's important to consider the vulnerability happening in conversation about code. If someone has just said the "wrong" pronunciation for the first time, there's almost certainly an experience mismatch or the element of entering into a conversation about this topic. As far as courses go, I think it would have been cool if the instructor in the first course I took mentioned that you can pronounce it either way, but creating course material is also a pretty specific scenario.

I always appreciate professors who remember to mention that either way is ok to their students during a lecture. It's something I might not have noticed if I didn't have such a bad experience, but honestly I think if "it doesn't matter" was the accepted stance, there might be fewer arbitrarily truncated conversations in this particular arena between students/jrs. Or maybe they'd just be arguing about tabs v spaces or the best editor or pineapple on pizza instead. I think SQL/sequel is different, though, because when you're learning a topic and get checked on your speech on what is basically the name of the topic, internal monologue can get to "I thought I understood this at least a little, but I don't even know what it's called" pretty fast. With tabs v spaces, we all know we're right and we're absolutely going to keep doing whatever we've been doing.

A few years ago, I had a conversation with someone who was really into inclusive pedagogy and taught math but coded a bit as well. He pronounced it squill (rhymes with 'quill') intentionally every. time. It sounded a bit meme-y (a la chat gippity) and a lot ridiculous. It was actually kind of infuriating for a few conversations. Then, as I got used to it, I started to check my motives about being "right" and correcting people who are "wrong" about it.

It kind of reminds me of the process I went through when I moved to a city for the first time and realized that people who use 'incorrect'/'improper' grammar are (a) completely intelligible and (b) not wrong for doing it. I let go of my hard-won feeling of being the most "correct" at grammar and realized maybe I was doing talking wrong. It wasn't until I came to this realization that I started to understand rich layers of meaning in speech I used to hear but wrote off in lieu of listening.

I still feel like I'm pretty good at diagramming sentences, but I stopped letting that be a determining factor in conversations before they even started. The reason I ever did was because I worked so hard to be good at English grammar. I worked so hard to get good at English grammar was because I was given positive feedback for speech and writing that was academically correct and disproportionately harsh feedback when I made mistakes. My sense of self was wrapped up in it. Now, when I remember the times I corrected other people for how they said something as I assumed I understood what they were saying. I'm sure I missed out on a lot. Plus: it would take me at least 60% more time to write a blog post if I edited it to what my standards used to be before publishing it.

This post is not directed at any person in particular. Posts on x are very different than real-life conversations and it's a good place to just have a take and really commit to it. I genuinely like the idea of squill or even squeal because they're jarring. Considering why we think something is correct can prepare us for how important that correctness is going to be in a conversation that will maybe someday happen. I've been practicing taking myself less seriously and my enthusiasm about learning and talking about code more seriously. I'm still not there. I have become much more comfortable saying "I don't know" and jumping straight through the sting of embarrassment into actually listening to the answer.

I don't care how you pronounce SQL. I care very much that you said SQL, and I would love to hear what you're going to say next.

Pest-Driven Development: Learning, Iterating and Project Planning

Mary — Thu, 14 Sep 2023 15:13:48 +0000

This is another relatively nontechnical post. It's a longer one about learning and TDD. This series has been conversational. It's a little bit of an exercise in failure, part performance review. Here's a whole bunch of opinions:

I think there comes a points in every developer's career when they understand the fundamentals, understand a bunch of "known unknowns" about what they need to learn (in the sense of information consumption/acquisition), know a few "known unknowns" about what they need to improve (in the sense of mindset/style) and then see what they're able to produce. This is the stage of any new discipline when I start to engage with how I'm learning. I do this in lots of ways: consuming information about known knowns (taking courses, following tutorials, reading documentation, reading books, watching videos) and known unknowns (watching streamers with a lot of experience and/or a systems-thinking approach, listening to podcasts where people discuss coding in more abstract terms, reading books like 'the pragmatic programmer' and 'clean code', reading code that is well written).

So I get this input and I have to deal with how that doesn't line up with my "known knowns". I see it in my output, and I want to get better, but it's not possible to prepare for unknown unknowns or to avoid them. Whenever one is learning a new skill, the unknown unknowns are the most important pieces.

A New State of Mind

It's good to take a break and think about how to get from point A to point B in the following series of things. Here's some definitions:

A. output: producing code that is fine, I guess, but could be implemented better (known knowns). Your body of work until now.

A′ (A "prime"): producing output that is pretty ok. Your current project(s). You don't have to google much to work in this area

B. improved output: the a body of work you're currently challenged when youre interacting with, where you start ennumerating and sometimes incorporating things you know you should know (known unknowns)

C. improved thinking and processes: finding a better way to incorporate things you know you should know (known unknowns)

X. idealized output: producing code that contains things you know you should know with a better process than you have now (unknown unknowns)

It is my personal opinion that no one ever gets to point X (idealized output). Instead, we aim to shift the goalpost. And as this happens, point A (output) improves until the output looks like point X (idealized output) to someone else. Let's call that space A′ (current output that seems a little better than previous output). And all the things that happen at point B ("reach" output) and the behavior that happens at point C (improved thinking) are too much to impart directly to another human because

it would take too long
expressing everything that happened during a shift like this delays or even prevents another

The production of educational material for other people is a side effect of C (improved thinking/processes). But writing code productively at point A′(current code after learning something) and writing the best tutorial or course material after learning something are not the same activity at all. The best tutorial you can write at a given point A is more like an emergent property than a part of this system at all.

The ability to talk about code as you're doing it can also be a side effect of point A′ (live coding in your comfort level or describing code you've already completed) but also a completely separate process. It's harder to verbalize code at point B (improved output) and REALLY hard at point C (improved thinking) before a new concept has been integrated into long term memory and can be applied to additional processes. Interview prep and pairing can increase our capacity to describe what we're doing and thinking as we code as it is being written.

Because it's difficult to ask a person about what they're learning and easy to ask a person about what they're comfortable with, I think it's also a limitation of live coding interviews. I also think evaluating more recently integrated concepts and how comfortable a person is at point C (improved thinking) is a more valuable evaluation of a programmer than their A′ (body of work). This makes the methodology of producing and grading performance evaluations vastly more complicated. It's also a valuable quality to be comfortable going through this A->B->C->A′; progression in rapid succession over and over and over again. There's a marginal increase in cognitive load and discomfort in these iterations. ESPECIALLY for new programmers.

Occasionally when you're trying to improve, you encounter a complete dumpster fire of a situation and have to think about how to recover from it, like a Giselle in the wild shaking itself off after it realizes that it's been debugging in the wrong directory for like 8 hours. Mixed metaphor there. There can be an emotional aversion that comes with this type of block.

I'm taking this course where I'm watching code being written in the frameworks I'm using in my project. But when I finish the course, I'm not going to be at the instructor's point A when he wrote the course. I'm going to be at my point X from when I started asking questions about TDD.

Updated Goals

Now that I've learned a bit more, I realize it is useful to reorganize my first post in this series with some takeaways I've gotten up the point where I am now. I reserve the right to take all of this back, btws.

1. Pause after every new test passes and ask yourself what you're going to do next.

This is my favorite takeaway from this course. We don't just see coding, we see pausing. This is probably even more important than code.

It stops me from making reckless decisions and breaking the code I just ensured is working. This is apparently one of my hobbies. It's been pointed out to me by other people "a couple two three" times.
I can only choose one next thing to do. If something occurs to me after I've made a decision and have begun writing code, I often just forget about it. Once I've reached a milestone with code behavior, an opportunity arises. Valid options of next steps present themselves. Multiple decisions can be made in this moment, but if you rush you may think of a bunch of possibilities, choose one, and go off without fully separating it from the other possibilities. It's hard to stay task-focused with numerous possibilities in mind. I sometimes experience leakage from discarded or postponed options as I pursue the task I've selected. This is not great for code quality.
Thought is habitual. The patterns we're used to using become learned and the coding patterns we use tend to affect the way we live and vice versa. It's called neuroplasticity (if you are unfamiliar and want to google it) and it's incredible. Coding is a subset active thinking, programmers have a disproportionate responsibility to take regular breaks and manage distractions and interruptions; we also tend to have sprint assignments and meeting-filled schedules and slack/discord channels that sabotage this. If we are impulsive or self-critical or doubt-filled in our coding, we risk the amplification of these tendencies during other activities. There's this concept of "the sacred pause" in mindfulness. Mindfulness is the real benefit of TDD that causes the well-documented side effect of clean code despte the potential drawbacks. I've already seen an improvement in my overall well-being since I started making blade templates just from the randomly generated quotes produced by the inspiring class.
It gives you the opportunity to write the other possible avenues down and contributes to your engineering daybook. There's this idea that we value a group of potential choices in comparison to each other. Since one can best follow one train of thought at a time, programmers usually have exactly one choice they can pick at each of these opportunity points. We choose the best right thing at the cost of not implementing the other choices. In economics this is called opportunity cost. A forgotten possibility that was the 2nd best or 3rd best option at a moment of opportunity might be more valuable than the 1st best option that comes to mind at the next juncture. It's easy, even probable, to forget about a current task's substitutes while writing code for it.

If I'm in a flow, I'm much more likely to make a choice in my comfort zone and postpone a task I know I would have to research. But I definitely won't research it later if I forget I was going to do it. This is why I've been meaning to look into redis for years. YEARS. Taking time to write down alternative options to implement but aren't choosing to implement now retains value.

Here's the flowchart:

2. Test the smallest thing possible so you have a test.

Write a more complicated test later. Or refactor the test later. When you're in the moment, you want a test that works. Avoid hard coded values in completed tests, but use them when you're making sure your test doesn't break the very time you write it. A failing test is the starting point of the last decision you made, not the final product. Even if the imaginary people who are going to make fun of your code and call you stupid (ignore this if you're not relating, but if you are read this or watch it) are looking at your public github repo, they're not going to your test suites first. That would be insane. So you can be clunky at first.

3. Take time to refactor.

There's a whole video about this in the course. Watch it. Tell me what you think in the comments.

4. Don't make your tests clever.

(See point no 2.) The functional utility of a test is pretty much self-contained unless you're working with arbitrary coverage requirements imposed on you by someone else. If you care about your coverage the simpler the tests you write are the more confident you can be that your code is working as expected. If you have to choose between brittle/fancy and robust/simple, KISS. If you are being forced to test for information that is not useful, whoever imposed those requirements doesn't deserve your clever. Save it for leetcode.

Updated Project planning

I'm pausing after the introduction to jetstream to re-evaluate my previous project planning. I made a bunch of wireframes (as suggested). That really helped me think about what behavior I wanted to have and how that should be implemented (as promised). Previously, I had organized my goals by role. Now I want to think about testing the smallest thing possible, and planning coverage to match the parts of ui that matter the most. So I'm going to sort them into actions instead, because this is how I will implement (policies)[https://laravel.com/docs/10.x/authorization#creating-policies]:

`create` (organizers and administrators only)

a new task

`read` (all users)

a single task
a list of tasks
a list of tasks that are currently unassigned
sorted lists of tasks
a list of all tasks assigned to a single user
dashboard including paginated, limited tasks

`update`

assign one's self to the volunteer attribute of a task ([volunteer](#confirm-organizers-and-adminstrators-only)) (all users)
all fields (organizers and administrators)

`delete` (adminstrators)

Deletes a task completely.

`cancel` (organizers and administrators)

This marks a task as cancelled but does not remove it from the system.

Mark `complete` (all users)

Indicates the task is done to be confirmed by an admin or organizer managing a contract

`confirm` (organizers and adminstrators only)

Indicates the task was done correctly and (eventually) updates the status of the task as it relates to the contract

`volunteer`/`un-volunteer` (all users)

The only update action a volunteer role permits.

volunteer: Update a task to store the current user as the volunteer.
un-volunteer: Remove current user currently assigned to a task from the task.

`assign`/`un-assign`/`reassign` (organizers and administrators only)

assign: Store any user id associated with an organization to a task.
un-assign: Remove a user id associated with an organization from a task.
reassign: Update a task to store a new user id from a task.

inb4 Laravel Was Never Bad

I'm starting generally to make a point about dilution. There's been much of discussion lately about PHP Doesn't Suck Anymore, a title potentially offensive to people who never thought PHP sucked but generally embraced by many people who like memes and have ever been on the internet. PHP is not my favorite language. I didn't really choose to learn it. It's kind of gnarly. However, Laravel is definitely my favorite web framework. So as a person trying to learn PHP and a fan of sincere posting, I have seen this video several times. I also watched the primegean react to it live so I could get context and listened to several podcast episodes in which it's discussed. It's basically a list of things in modern PHP that are good with code examples and names of things so you can research them. If you really get into it and spend like 20 hours reading the docs on every feature listed (an example you know really happened because it's too specific to be made up) you can learn tons about how PHP is different from other languages and intuit what it's good for and some best practices.

I also spent several hours on DNF form alone because I love relational databases more than anything else in computing and as a consequence I love (beginner level) set theory and relational algebra. Then, I started looking into DNF types. Then, I started looking into how these are implemented in the C family and Java. Then, I went down a rabbit hole of opinion posts on reddit and quora and stackoverflow about why it's even good when languages are strongly typed (the top answer will surprise you). Then, I took all of this knowledge and made what I consider to be the best meme I've ever made in my whole life. Then, I sent it to my buddy Tyler. My buddy Tyler is my closest friend, teacher and career mentor. We have spent hundreds of hours chatting about code and tech and the like, so we have a pretty established language and understand pretty well what the other person knows about. He hadn't seen the video yet but he is a professional PHP developer and when he didn't immediately get this super specific meme I was absolutely shook. He has since seen it and now gets it but here's what I am trying to say: it's really difficult to say a complicated thing to another person when you know about it while respecting the amount of concepts and sheer jargon that make up a language or framework.

"The main dangers lie in the "unknown knowns"—the disavowed beliefs, suppositions and obscene practices we pretend not to know about, even though they form the background of our public values." - Slavoj Žižek

It is so difficult to distill experience into understandable technical communication that I can be totally blindsided by saying a thing that is clear to me and maybe 5 other people to a 6th person who isn't familiar with the exact group of concepts you are talking about. We contend not only with our own unknown unknowns but with our audience's unknown unknowns when we communicate and produce educational material and write documentation. That's why pest and especially the pest documentation is so impressive.

If you check out the pest documentation expectation API you'll get an overwhelming list of test cases that are extremely readable and applicable for specific groups of tests. That is a LOT of distilled testing experience just sitting there waiting to be considered. And you can bet that each of them have a use case because no one just make a random function, who has time for that? Nobody at PHPUnit, either, who have additional assertion docs which I found because I was reading Pest docs. Also: no matter how you feel about PHP, it is extremely popular. I heard Wordpress alone powers 98% of the web. I think this list is an incredible resource not just for writing tests with pest but also for understanding what is a useful thing to test for. Here's a bullet point version of some of "the many uses of tests" from The Missing Readme on pg 89:

check that your code runs and behaves as expected
protect code from changes that may unintentionally alter behavior
encourage clean code
force developers to use their own APIs
document how components are to be interacted with
serve as a playground for experimentation
force a developer to think about the interface and implementation of their new program (as well as the dependencies they choose)
serve as documentation

This is true of Laravel documentation in general. I'm really going out of my way here not to accidentally imply that Laravel got better recently after starting with that anecdote about PHP Doesn't Suck Anymore. One thing I've heard from Laravel developers in podcasts and in the conversations I've been privileged to have with some of them recently is this: read the entire documentation. This is getting back to The Curse of Knowledge territory again and I know it sounds dangerously close to 'just read the docs', but when I get the same advice from like 30 people in the span of a month I want to pass it on. I also recently got RayCast and have been using the shortcuts for tailwind and laravel and vim and let me tell you: peak experience. 10/10 highly recommend.

"Learn Laravel", they said. "It Will Make You Better", they said.

This is more about personal stuff than pest, but if you're still reading I'm glad you're here.

As a python developer who likes memes and have ever been on the internet, I had some opinions about PHP for a long time and let me tell you, they were not positive. During all those hours of talking to Tyler about code, I would tell him an idea I had for a flask project and he'd say some variation of 'yeah, that's a useful thing but Laravel already has it'. After like a year of this I broke down and started learning more about it and was really surprised about how much I understood intuitively about the packages and how they worked. I started learning Laravel to learn PHP in a way that made more sense to me after looking at frameworks in other languages, but I didn't expect how much it would teach me about how websites are structured. It's opinionated in so excellent a way it's accidentally broadly educational.

I've wanted to blog for a really long time, but I've never felt like I had anything to say that other people didn't already know. I've read many articles on DEV in the past decade and I wanted a DEV hat for a while. So after coding for a while as a hobby for myself for a while, I decided to try to meet people and maybe find a mentor. I got a DEV hat because I know the DEV community is wonderful and wore it to laracon because I heard the Laravel community is wonderful. But I was really not expecting how wonderful it is. I have learned so much and got to speak to so many wonderful people that my brain kind of can't handle it. And when I finally got it together to take up the challenge of working in public despite being super introverted and freaked out about it, it got reposed by some of those wonderful people almost immediately and I cannot express how included I felt or how rad I think it is that you're reading this.

And then I got a comment on my DEV post from someone in a DEV hat and I was like-- this is it. I've peaked.

Pest-Driven Development: Minimum Viable Routing

Mary — Fri, 08 Sep 2023 07:07:40 +0000

Now that I am passing a test when I hit the 'home' route, I'm going to add all the other routes that are already part of the app. tests/Feature/ExampleTest.php doesn't say a lot about what's happening when I run my pest command, so I'm going to rename the file and add all my tests for routes there with the format:

    it ('gives back successful response for the <page_name> page', function() {
        get(route(<page_name>)->assertStatus(200);
    });

I am putting this in bold and a quote because it is important: You Must End Your Test File Name With the Word Test or it will not be executed.

A habit I've been getting into since I've been working with laravel is searching for the name of a file or variable I'd like to rename and check out where else it appears in the app. I'm trying not to look at too much source code right now, but I do also check out the first few functions if the naming conventions are unfamiliar to me or the syntax looks interesting. So when I look for the whole path, I see it's in vendor/pestphp/pest/src/Plugins/init.pub. This looks like it gets run during install and there's a lot more files in the tests/Feature directory than are listed here.

Little story here: when I was on the smoker's deck at Laracon meandering in to a conversation about event sourcing that I think may have been immortalized in this episode of no plans to merge, I met Filip (@ganyicz) and told everyone I'm new to Laravel. Zuzana had just given her talk "The Curse of Knowledge" and we were all thinking about it, so he didn't want to say "just read the documentation". I know this because he said "Well, I'm not going to say 'just read the documentation anymore". So basically the first advice he gave me was that Laravel source code is easy to find, written very well and maybe even better than the documentation. He has since showed me how to source dive from inside the ide and a bunch of other useful things.

This is a habit I have really enjoyed so far and it has definitely improved my ability to read and write code. Hacks to the game right there. Sometimes, like this time, I don't find any necessary takeaways but I become aware of something I wouldn't have seen otherwise.

Making a new pest file is pretty easy with php artisan make:test and prompts. When I'm prompted for a test type I select Feature (Pest) and name it tests/Feature/SuccessfulGetResponseTest.php. I also uncommented Illuminate\Foundation\Testing\RefreshDatabase::class in the uses method of tests/Pest.php. When I run pest I get 10 failed tests:

This is wonderful news because while I did import my routes\web.php file, I have not updated my Http\Controllers\RouteController.php since it was created with empty methods and this code should fail. This feels like TDD is actually happening, and I have clearly a clearly defined goal: get the TaskController to work so this feature test suite passes.

Getting the Test Suite to Pass

I'm writing this as I work, so I am currently fighting every impulse I have to completely rewrite the entire application. I absolutely hate the code that's running now and the user interface makes me shudder. But this is not a development goal, it is a copy and paste goal.

Debugging when you're copying and pasting code is mostly soul-crushing. I hear that other people adhere to this methodology but I come from a different philosophy of iterative development and I'm really struggling to even copy and paste my own code.

One Eternity Later

It finally occurred to me that the component structure I was using before is too complicated. I wanted to just move the previous blade component structures that compose my views, but it's not even code I want in my completed app. It was only when I took a step back that I realized that a few of the errors I was getting had changed to 302s, which actually is the desired behavior from the app.

So I reorganize the tests I've written and sort them by what I'm looking for:

// expect 302 Routes
it('gives back successful response for the tasks.board page', function () {
    get(route('tasks.board'))->assertStatus(302);
});
it('gives back successful response for the tasks.index page', function () {
    get(route('tasks.index'))->assertStatus(302);
});
// ... 2 more tests of the same format 

// expect 200 routes
it('gives back successful response for the home page', function () {
    get(route('home'))->assertStatus(200);
});

// expect 200 routes with variables
it('gives back successful response for the tasks.display page', function () {
    get(route('tasks.display'))->assertStatus(200);
});
it('gives back successful response for the tasks.confirmCreate page', function () {
    get(route('tasks.confirmCreate'))->assertStatus(200);
});
// ... 5 more tests of the same format

And when I run pest again I see that 5/10 tests are passing.

Viewing Expected Data On Routes

I made some assumptions about what I should be testing for that really complicated things. The next part of the course includes a test that made me think that writing a test for tasks.display should look something like this:

it('gives back successful response for the tasks.display page', function () {

    // create tasks using the factory() model
    Task::factory()->create(['task_description' => 'Test Task 1', 'sheets_id' => 1, 'public' => false]);
    Task::factory()->create(['task_description' => 'Test Task 2', 'sheets_id' => 2, 'public' => false]);
    Task::factory()->create(['task_description' => 'Test Task 3', 'sheets_id' => 3, 'public' => false]);

    // assert that the tasks are visible on the page
    get(route('tasks.display'))->assertSeeText(['Test Task 1', 'Test Task 2', 'Test Task 3']);
});

In order to get this output, I needed to start with a visible route. It took a LOT of time to clean up my existing/broken components so I could actually view this route, and digging through my messy code and sorting through what I needed to keep and get rid of just to pass variables through nested blade (the php templating language I'm using with laravel and jetstream) components had me absolutely philosophizing about trees, completely unaware of the forest.

At one point during this process, something happened with git that duplicated every file in my vendor folder and broke all of my tests except the example unit test that confirms that true==true by attempting to run each migration twice every time I ran a test. Since I was distracted by refactoring components and I thought most of the changes I'd made were in related to either components or pest, I thought that the issues with the database were related to the Illuminate\Foundation\Testing\RefreshDatabase::class. Then, when I tried to refresh the database with php artisan migrate:fresh and php artisan migrate:refresh and they both failed, I started going down the rabbit hole of sqlite and testing environments and yada yada yada. I rarely open my vendor folder (or its equivalent in other frameworks) or even think about it, so it was a pretty frustrating thing to debug. By this point in the forest metaphor I was basically staring at a leaf in a magnifying glass. Rough 24 hours.

So I finally had a visual confirmation of the component and exactly one vendor folder, and I started to refactor my code for the tasks.display route:

it('gives back successful response for the tasks.display page', function () {
    // create tasks
    for ($x = 0; $x <= 10; $x++) {
        $task = Task::factory()->create(['task_description' => "Test Task $x", 'sheets_id' => "$x", 'public' => false]);
    }
    $tasks = Task::all();
    $descriptions = [];
    foreach ($tasks as $task) {
        array_push($descriptions, $task->task_description);
    };
    get(route('tasks.display'), ['tasks' => $tasks])->assertSeeText($descriptions);
});

^ definitely don't do this, it does not pass and is cringe

Before I realized that (1) this is a really bad test to start with and (2) this is almost definitely a really bad way to think about this endpoint.

It's a bad test to start with because my tasks.display should only list upcoming tasks a user already assigned to themselves. tasks.show should display all the tasks with filters and pagination and the like and tasks.board shows a volunteer dashboard that emphasizes upcoming unassigned tasks and other tasks marked as important. Plus, I was too busy considering trees and leaves and the like to really consider what text I should be checking for and designing how the route should work. Woof.

It's almost definitely a really bad way to think about this endpoint because if I can figure out how to test simpler endpoints (ones that have tasks that should be visible to everyone, and then ones that have tasks that should be visible to everyone with some tasks being filtered out), I'll have a much better sense of how I want to go about presenting tasks a user has signed up for.

So I realized all of the tests here should be rewritten to just check if a page loads or not. I'm going to add other behavior to other test files later. I finally wrote a passing test I feel ok with for tasks.display because I thought this through: when I build out this method in the controller, I don't want to pass anything at all; I can get the user from the $request object

it('gives back successful response for the tasks.display page', function () {
    get(route('tasks.display'))->assertStatus(200);
});

This fails with a 302. And then I renamed the route from '/tasks/user/{user}' to '/tasks/user' in app/routes/web.php and rewrote the display() function in my app/Http/TaskController.php to:

public function display(Request $request)
    {
        $user = $request->user();
        $userTasks = Task::all(); // change this when assignment is working
        return view('tasks.display', ['tasks' => $userTasks, 'user' => $user]);
    }

But I'm not sure why I'm getting a 302. At least I've gotten to a level where I realized that a lot of the tests I considered to be passing actually aren't because I'm getting 302s instead of 200s and I don't have that many redirects in my routes. So I intentionally changed the controller to pass ['tasks' => $userTasks, 'user' => $user] and checked it out in the network part of the console. 500. And THEN the lightbulb went off-- I had already added authentication middleware on all the methods I'm getting 302s for, but I'm not writing tests for authenticated users. I guess I could spin it in a more positive way and say I'm already doing some work for testing my security groups, or hope someone else completely new learns from my mistakes. It's pretty frusterating right now. A 302 (redirect) is still information -- it's not a 404 (not found) or any other kind of error, and that was the goal.

10 Passing Tests

The final version of the test that tasks.display is working turned out to be:

it('gives back successful redirect response for unauthenticated users for the tasks.display page', function () {
    get(route('tasks.display'))->assertStatus(302);
});

Generally, the format for the tests on protected routes is:

it('gives back successful redirect response for unauthenticated users for the <route name> page', function () {
    $task = Task::factory()->create(['task_description' => 'Test Task 1', 'sheets_id' => 1, 'public' => false]);
    get(route('<route name>', ['task' => $task]))->assertStatus(302);
});

With the one exception of 'tasks.confirmStore'. This route gets a 405 (Method Not Allowed) because it should only be accessed by a redirect after a task is stored by a user.

What I learned

Since I published the first blog post, I've heard opinions from a few people who said they've tried TDD but couldn't stick to it and some more people that said they've never tried it but have been meaning to get around to it. I've heard from exactly one person who says he uses TDD as a methodology, and that was the instructor of the course. In the course recording. Before I started writing this. There's definitely problems with sampling here, but maybe the most important takeway I've had is that this is absolutely not required.

I started writing this post about 48 hours ago, and I was hoping to have it published at least yesterday. Completing it has been a milestone that kept me focused on TDD, and TDD has been a practice that allowed me to solve a pretty overwhelming bug. Normally I would have completely given up by this point, or started greenfield. So I can confidently say at this point that this is a methodology I really like for projects, especially if you're like me and just like liking things so much that you can get distracted when the next bug or endpoint calls. But it's a very cognitively challenging practice to implement these tests if you don't start out with them and let the test suite grow with the app. Too many spinning plates.

My buddy Tyler told me when he writes tests, he usually looks for access to a resource and validation rules and very little else. And then there's people who don't write any tests.

I'm making a commitment to myself to:

Finish the entire course
Add the types of testing described in the course to the project until I meet the (limited) goals I made in the first post in this series. Then I'll decide what to do as the project expands.

Pest-Driven Development: Literally The First Test

Mary — Fri, 08 Sep 2023 03:12:18 +0000

The next step is to actually install pest. If I was truly practicing TDD, I would have done this when I started my laravel application because Test-Driven Development is a lifestyle with a history and a community I may as well take a moment to put my hand over my heart and remember out loud that I'm uncovering better ways of developing software. But that's okay, because pest works 'on top of' an existing repository, and when you install it a folder of tests is created.

> composer require pestphp/pest --dev --with-all-dependencies
> php artisan pest:install
> composer require pestphp/pest-plugin-laravel --dev

Protip for my fellow beginners and tired people: definitely run these commands inside the directory that contains the app folder; it's not a global install. I also forgot to add the pest plugin and curly braces which threw me for an hour or so, so do remember that last line. We'll need it, and vs code is different than phpstorm.

Also, it's my personal opinion that when your terminal asks you to give a star to a repository on github that's going to save you hours of toil and heartache, actually taking the time to do it is the same thing as unlocking an achievement in real life. And then you can go back someday and see all those stars and realize how connected you are to all these people who are a lot like you and how much you learned from their hard work. But again, I digress.

Then you can open your /tests/Feature/pest.php file and check out your new pest file, which looks like this on my fresh install:

<?php

namespace Tests\Unit;

use PHPUnit\Framework\TestCase;

class ExampleTest extends TestCase
{
    /**
     * A basic test example.
     */
    public function test_that_true_is_true(): void
    {
        $this->assertTrue(true);
    }
}

But the very first test in the course confirms that a request to a route returns a status code of 200. We'll take out all of the code in the file and replace it with

<?php

it('gives back successful response for the home page', function () {

    $response = $this->get('/');

    $response->assertStatus(200);
});

So what's happening here? I think it's a fair time to stop and think about this question, especially because the code contains it and this.

Let's just talk about `it` for a minute.

From passing knowledge, to me it indicates Keyword-driven testing, which "separates the documentation of test cases – including both the data and functionality to use – from the prescription of the way the test cases are executed". Pest isn't the only option for testing, even in laravel, but I'm choosing it because its 'claim to fame' is allowing a developer to use less code to write tests and allow that code to be more readable. So it makes sense that people new to testing (me) are going to run into some unfamiliar keywords. The apperance of it combined with the extremely human-readable description as the first function parameter gave me pause. So I looked it up the pest source code, and got

if (! function_exists('it')) {
    /**
     * Adds the given closure as a test. The first argument
     * is the test description; the second argument is
     * a closure that contains the test expectations.
     *
     * @return Expectable|TestCall|TestCase|mixed
     */
    function it(string $description, Closure $closure = null): TestCall
    {
        $description = sprintf('it %s', $description);

        /** @var TestCall $test */
        $test = test($description, $closure);

        return $test;
    }
}

It looks like it takes the description, adds it to the string 'it' and formats it to use it as a label for the callback we're passing in the second parameter. Then, when pest actually calls test() we have the super readable label and the function. test() has the same method description as it, but now our description is formatted for later and we can see things starting to really move inside the test() function (despite the syntax of the two function calls looking similar):

if (! function_exists('test')) {
    /**
     * Adds the given closure as a test. The first argument
     * is the test description; the second argument is
     * a closure that contains the test expectations.
     *
     * @return Expectable|TestCall|TestCase|mixed
     */
    function test(string $description = null, Closure $closure = null): HigherOrderTapProxy|TestCall
    {
        if ($description === null && TestSuite::getInstance()->test instanceof \PHPUnit\Framework\TestCase) {
            return new HigherOrderTapProxy(TestSuite::getInstance()->test);
        }

        $filename = Backtrace::testFile();

        return new TestCall(TestSuite::getInstance(), $filename, $description, $closure);
    }
}

it and test mean so much in the context of testing they mean almost nothing, so I think this bit of new context is enough to give a little more meaning to what I'm reading.

What even is `this`?

I want to take a minute to dive into this, but I won't. Without fail, when I'm in a pairing situation and I ask a php dev what this is, I'm told we'll 'get to it later' and then we write actual code and that's probably a good thing. I know that this refers to the calling object, and there's always a moment when I'm reading or writing code in laravel as a beginner where I guess at what this is in a new context. This is no exception. I'm definitely going to come back to it in a later post, but if someone wants to have mercy and just tell me what I am calling get on (is it the whole app??) that would be great.

Some More Setup

Before I stepped back, I took a minute to create a pest alias. By default, you can run a test with ./vendor/bin/pest but I changed it to pest. If you're reading this and you haven't already-- don't forget to alias sudo to please.

Then I hopped into the phpunit.xml to uncomment:

<env name="DB_CONNECTION" value="sqlite"/>
<env name="DB_DATABASE" value=":memory:"/>

which results in a super lightweight and separate testing database. And that reminded me of this one episode of No Compromises that I heard while driving to Nashville. Super hype for my first testing database.

Getting Pesty

The next part is to refactor the test code to make it more read more pest-y. First, we'll

change $response = $this->get('/'); to get('/');. That requires use Pest\Laravel\get, but it looks much nicer.
specify a named route using the route() helper instead of passing the string /. Now we have get(route('home')).
remove $response->assertStatus(200); and call assertStatus(200) passing the 200 OK status code as a parameter. Now the entire file looks like:

<?php

use function Pest\Laravel\{get};

it('gives back successful response for the home page', function () {

    get(route('home'))->assertStatus(200);
});

Another tangent: I listened to APIs, with Jess Archer on The Laravel Podcast today and there's a ton of useful information about returning HTTP status codes and why being specific about them is useful, and I'm really looking forward to seeing what can be done with that and pest.

Since I'm using jetstream, I saw a lot of output. They're listed by path alphabetically. But check it out: it does gives back successful response for the home page. Feels good, man.

Pest-Driven Development: Project Planning

Mary — Thu, 07 Sep 2023 18:43:45 +0000

The project I'm making is very similar to a to-do app in many ways, which is great because I've made 5 or 6 of them in other languages already. This is my first CRUD app in Laravel, so I'm trying to balance learning a new framework and philosophy with trying to keep my MVP simple and usable. It's a real struggle so far.

In episode 1, Christoph discusses the benefits of test driven development including a focused method of iterative development (I'm paraphrasing) and the practice of refactoring integrated into the development process. These both sound fantastic-- how many of us have (the benefits of) real tests? TDD is a topic of contention in whichever language you choose, and generally so far I've taken the advice: if you don't have users, you don't need tests. I've eschewed cleaner coding practices for a more complicated, bloated, and completed program. Then, I've proceeded to use those programs myself and look at my code months later while considering adding a new feature and wonder: who even WROTE this? But today is different. Today, I have users.

I'm going to start describing this project by including some behaviors I want users to be able to experience when they use the app. This is also an exercise in the first video of the course. I will write a clearer summary soon, and part of describing it requires separating types of behaviors and the authentication roles required to interact with each type of behavior. For example, the to-do behavior of the application has different 'user stories' for events (tasks that are associated with an appointment date and time) than for a more general task class. So let's start by just talking about the event-type tasks-- not because this is the way I'd ideally like to develop, but because appointments are more urgent to the users of the app than tasks are(1).

Volunteers

The future 'about' section of the app (currently a draft) describes volunteers of the application as:

[users] who have already established functional processes through experience in their domains and are willing to provide insight to contributing developers and to administrators about how technical solutions may improve their ability to help others in their community

Volunteers should be the most numerous user group type, the type of user that can see the fewest features of the app. But the app is mostly for them. So I'm thinking about designing the interface mostly around what the volunteers will be able to see. Unlike a typical to-do app, volunteers don't make the tasks; the user dashboard will be kind of like a job board in that way. But they should be able to sign up for tasks, interact with tasks they've signed up for, and get more information about those tasks really easily. Even if that usability comes at the expense of extra bloat the Administrators and Organizers-- because the goal is to get feedback to improve functionality, and I don't expect much useful feedback from users who are bogged down in complicated flows and don't have a solid understanding of how to do what they need to do. But I digress.

For now I'm going to focus on testing that volunteers:

can view a list of tasks
can view sorted lists of tasks (tasks assigned to them, budget, etc)
can sign up for a task
can remove themselves from a task
can add additional info for a task
can mark a task as completed

Organizers

The 'about' section of the app refers to organizers generally:

Administrators and employees of nonprofit organizations who (a) can benefit from project organization and task automation, especially in cases where the reduction of time allocation for administrative tasks may be allocated towards the scope/scale of their organization's output and (b) are willing to advocate within their organization for more effective and compassionate processes

Employees are actually a different auth group from organizers, but that about isn't written as a way to think about code. So I'm taking the time to consider more clearly. Administrators have a more global idea of what needs to be done in the organization. But a less granular goal for behavior doesn't translate into a more obvious design. Because they know what needs to be assigned and has to get done and are responsible for creating tasks and maintaining them to completion, and because volunteers need to have a very simple experience, designing for administrators means considering complexity and bloat. These users aren't necessarily more available (to use and learn the app) or more technical than the volunteers-- I think these are assumptions that other organizations can make more safely.

Organizers:

can view a list of tasks
can create tasks
can edit all task fields
can view sorted lists of tasks (tasks assigned to them, budget, etc); can sign up for a task; can remove themselves from a task (this is the same behavior volunteers should have)
can assign a volunteer to a task
can unassign a volunteer from a task
can cancel a task (this shouldn't delete the task)
can delete a task created in error
can add additional info for a task (optionally in response to requests for additional information-- let's handle this later)
can mark a task as completed and confirm a task has been completed; a confirmation from this role means something different for the state of the task (and the checklist) than a volunteer's confirmation.

Administrators

For now, administrator roles mostly have additional functionality with behaviors that aren't directly related to events. Paid employees who choose to use the app fall into this category, as do some organizers who need escalated permissions.

One of these behaviors is going to be adding Organizers and Volunteers. Most of this behavior is going to be handled through the Teams feature of Jetstream (yay!) but there's some domain-specific logic that I'm also going to ignore for right now. Another behavior will be handling contracts, groups of tasks not unlike a Jira epic. Contracts and tasks will both have similar completion states, and this is something that also has to be on the back burner while designing these tests.

So that's the first post about reteer. And my first DEV post. I'm hoping to write my first tests today and get some additional functionality by the end of the day. Anything worth doing is worth doing badly-- and I think this is a project worth doing. If you do too, say hey.

Oh, and the project is:

Reteer is an open source application being designed to reduce organizational overhead within volunteer organizations. It is designed for groups with extremely low budgets who rely on donations and volunteer work to do good.

(1). Actually, there's going to be at least two more role types in the application than we're going to discuss now. I have a brainstorming User Actions document that has more behaviors and groups than this post contains, and I'm trying to be okay with letting them sit for a while.