✍️ Blog #23: What I Learned About Annotations in Playwright

When I started, I thought writing tests was just about getting them to pass. But as the number of tests grew, I realized that being able to control which ones run, which to skip, and how to debug easily — is just as important.

Let me take you through everything I’ve learned so far about Playwright’s annotations.

🔍 What Are Annotations?

Annotations are special helpers in Playwright that let you modify test behavior without changing the actual logic of the test. They're great for:

• Focusing on a single test (test.only)

• Skipping unfinished or flaky ones (test.skip)

• Flagging tests that need fixing (test.fixme)

• Allowing known failures (test.fail)

• Marking slow tests (test.slow)

Think of them like post-it notes or switches you can stick on your tests to manage them better during testing.

✅ Test-Level Annotations

These annotations go directly on individual tests.

🧪 test.only – Focus on One Test

test.only('run this test only', async ({ page }) => {
  
// test steps

}); 

This runs only this test and ignores the rest. I use it when I’m debugging a specific case and don’t want to wait for all tests to run.

🚫 test.skip – Temporarily Ignore a Test

test.skip('skip this test', async ({ page }) => {
  
// test steps

});

The test is completely skipped and marked as such in the test report.

🛠️ test.fixme – Mark Test for Future Fix

test.fixme('broken on staging', async ({ page }) => {
  
// test steps

});

This helps remind you (and your team) that a test needs attention. It’s like a TODO for your test file.

🔁 test.fail – Expect a Test to Fail

Sometimes, I have tests that are expected to fail, maybe because of a known bug.

test.fail('this is expected to fail for now', async ({ page }) => {
  
// Know failure case

});

💡 If the test unexpectedly passes, Playwright will show an error — so you don’t forget to remove the fail flag when the bug is fixed.

🐢 test.slow – Mark a Test as Slow

Some tests — like file uploads or third-party API steps — take longer. You can use:

test.slow('this test takes longer', async ({ page }) => {
  
// slow  test 

});

This increases the timeout for just that test. I found this useful when tests failed just because they were a bit slow.

📂 Describe-Level Annotations

These apply to groups of tests, using test.describe.

🔍 test.describe.only

test.describe.only('Login tests', () => {
  test('valid login', async ({ page }) => {});
  test('invalid login', async ({ page }) => {});
});

Runs only this group of tests. 

🚫 test.describe.skip

test.describe.skip('Admin dashboard tests', () => {
  test('edit user', async ({ page }) => {}); 
});

Skips the whole group. I used this when a feature wasn’t ready yet, but I had already written the tests.

🛠️ test.describe.fixme

test.describe.fixme('Tests broken on mobile', () => {
  test('open menu', async ({ page }) => {});
});

Similar to test.fixme, but for a whole group. Useful for flagging big areas that need review.

💡 Summary Table

🚀 Final Thoughts

Before I discovered annotations, I used to comment tests out when I didn’t need them — and it got messy. But now, with these simple tools, I feel more in control of my test files. I can:

• Focus on one test

• Skip ones I’m not ready to run

• Leave reminders for broken tests

And most importantly — I can debug and test with more confidence.

This blog is just another small step in my Playwright journey, and I hope it helps you too! If you’re also learning, I’d love to know how you use annotations or any tips you’ve picked up!