✍️ 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

Annotation	Purpose
test.only	Run only this test
test.skip	Skip this test
test.fixme	Mark test needing fix
test.fail	Mark as expected to fail
test.slow	Increase timeout
test.describe.only	Run only this block
test.describe.skip	Skip the entire block
test.describe.fixme	Flag group for future fix

🚀 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!